O”Reilly Media，lnc. 介 绍 


O'” Reilly Media 通 过 图 书 、 杂 志 、 在 线 服 务 、 调 查 研究 和 会 议 等 方式 传播 创新 知识 。 自 1978 年 开始 ，O” Reilly 一 直 都 是 前 沿 发 展 的 见证 者 和 推动 者 。 超 级 极 客 们 正在 开创 着 未 来 ， 而 我 们 关注 真正 
要 的 技术 趋势 一 一 通过 放大 那些 “细微 的 信号 ”来 刺激 社会 对 新 科技 的 应 用 。 作 为 技术 社区 中 活跃 的 参与 者 ，O” Reilly 的 发 展 充满 了 对 创新 的 倡导 、 创 造 和 发 扬 光 大 。 


mn 


O” Reilly 为 软件 开发 人 员 带 来 革命 性 的 “动物 书 ”; 创建 第 一 个 商业 网 站 (GNN) ; 组 织 了 影响 深远 的 开放 源 代 码 峰 会 ， 以 至 于 开源 软件 运动 以 此 命名 ; 创立 了 Make 杂 志 ， 从 而 成 为 DIY 革 命 的 主 
先锋 ; 公司 一 如 既往 地 通过 多 种 形式 缔结 信息 与 人 的 纽带 。O” Reilly 的 会 议和 峰会 集聚 了 众多 超级 极 客 和 高 瞻 远 瞩 的 商业 领袖 ， 共 同 描绘 出 开创 新 产业 的 革命 性 思想 。 作 为 技术 人 士 获取 信息 的 选 
择 ，O” Reilly 现 在 还 将 先锋 专家 的 知识 传递 给 普通 的 计算 机 用 户 。 无 论 是 通过 书籍 出 版 ， 在 线 服务 或 者 面授 课程 ， 每 一 项 O” Reilly 的 产品 都 反映 了 公司 不 可 动摇 的 理念 一 一 信息 是 激发 创新 的 力量 。 


业界 评论 


“DO”Reilly Radar 博 客 有 口 尼 碑 。” 


Wired 


“O”Reilly 赁 借 一 系列 (真希 望 当初 我 也 想到 了 ) 非凡 想法 建立 了 数 百 万 美元 的 业务 。” 


Business 2.0 


“O 〇 ”Reilly Conference 是 聚集 关键 思想 领袖 的 绝对 典范 。” 


“一 本 DO ”Reilly 的 书 就 代表 一 个 有 用 、 有 前 途 、 需 要 学 习 的 主题 。” 


Irish Times 


“Tim 是 位 特 立 独行 的 商人 ， 他 不 光 放眼 于 最 长 远 、 最 广阔 的 视野 并 且 切 实地 按照 Yogi Berra 的 建议 去 做 了 : “如 果 你 在 路 上 过 到 偏 路 口 ， 走 小 路 (岔路 ) 。” 回 顾 过 去 Tim 似 乎 每 一 次 都 选择 了 小 路 ， 而 
且 有 几 次 都 是 一 闪 即 逝 的 机 会 ， 尽 管 大 路 也 不 错 。” 


Linux Journal 


2014 年 3 月 21 日 ， 在 PHP 业 界 著名 专家 “ 乌 哥 ” ( 患 新 宕 ) 的 新 浪 微 博 (@Laruence) 下 面 ， 我 第 一 次 看 到 了 Facebook 公 司 的 Hack 语 言及 HHVM 的 相关 消息 。 出 于 敏锐 的 职业 嗅觉 ， 我 注册 了 相关 的 cn 域 
名 。 在 随后 的 周末 ， 内 第 一 家 Hack 语 言 的 中 文 站 (http://www-hacklang'org.cn) 和 第 一 家 HHVM 中 文 站 (http://www.hhvm.com.cn) 正式 出 炉 了 。 


一 个 月 后 在 中 关 村 的 翔 黄 大 厦 ， 我 很 幸运 地 碰 到 了 “和 急 哥 ”， 并 和 他 畅谈 了 理想 与 人 生 。 在 鸟 哥 的 启发 下 ， 我 不 久 后 就 来 到 了 新 的 工作 岗位 ， 开 始 了 新 的 生活 。 环 境 改变 了 ， 生 活 和 工作 也 路 上 了 新 的 
征程 。 

2016 年 3 月 21 日 (很 神奇 ， 也 是 3 月 21 日 ) ， 机 械 工业 出 版 社 的 绿 杰 编辑 找到 我 ， 洽 谈 翻 译本 书 的 相关 事宜 。 这 正切 合 我 内 心 深 处 由 来 已 久 的 想法 ， 即 翻译 一 本 专业 的 HHVM 和 Hack 编 程 技术 书籍 ， 在 中 
国 范围 内 ， 传 播 最 新 的 Hack 语 言 编程 技术 知识 。 我 非常 强烈 地 感受 到 ， 必 须 抓 住 这 个 机 会 ， 完 成 这 本 书 的 翻译 。 


在 2016 年 4 月 ， 我 初步 尝试 翻译 了 前 面 的 章节 。5 月 到 7 月 上 多， 完成 了 本 书 大 致 的 翻译 。 在 工作 之 余 以 及 周末 的 时 间 ， 我 都 在 反复 推 谢 英 文 原版 书 中 的 每 个 字句 ， 经 常 堵 夜 到 凌晨 两 点 ， 这 是 一 段 难 忘 的 
经 历 。 翻 译 同 时 也 是 不 断 学 习 提高 的 过 程 。 在 完成 初稿 后 ， 我 感觉 又 重新 认识 了 Hack 语 言 ， 也 重新 认识 了 PHP。 


在 2016 年 8 月 ， 刘 诗 汝 编辑 又 给 出 了 很 多 专业 的 修改 意见 。 然 后 ， 整 个 译本 又 经 历 了 几 次 脱胎 换 骨 的 变化 ， 才 最 终 呈现 在 广大 读者 的 面前 。 


最 后 ， 我 要 感谢 生活 给 我 的 磨 王 。 一 份 “不 服输 ”的 执 念 引 领 我 在 黑暗 中 不 断 探 索 前 行 。“ 不 经 历 风雨 ， 哪 能 见 彩虹 ”， 对 此 我 有 着 更 深刻 的 认识 。 我 还 要 重点 感谢 绿 杰 和 刘 诗 涵 编 辑 。 感 谢 他 们 在 茫 
茫 人 海中 发 现 我 ， 让 我 能 够 有 机 会 实现 内 心 最 深 处 的 愿望 : 让 Hack 语 言 编 程 技术 在 中 国 范围 内 得 到 更 好 的 传播 和 发 展 。 我 还 想 感谢 中 国 台 湾 作 家 张 德 芬 ， 正 是 她 的 身心 灵 三 部 曲 ， 伴 我 走 过 了 那 段 最 黑暗 的 
时 光 ， 让 我 能 够 有 机 会 学 会 接受 、 放 下 ， 学 会 通过 “宇宙 的 力量 ”散发 “心灵 的 喜悦 ”， 最 后 达成 “ 心 想 事 成 ”。 


Hack 语 言 和 PHP 的 伴生 与 博弈 不 会 停止 ，Hack 语 言 出 身 于 PHP， 而 又 “高 于 ”PHP 的 特征 ， 决 定 了 这 场 争斗 会 旷日持久 。 在 本 书 中 ， 你 可 能 会 体会 到 HHVM 及 Hack 语 言 的 使 用 者 对 PHP 的 一 些 激烈 言 
秤 。 同 时 ， 如 果 关 注 “ 鸟 哥 ”的 新 浪 微 博 ， 你 也 可 以 看 到 他 对 Hack 语 言 和 HHVM 的 一 些 反 击 之 词 。 熟 对 就 错 ， 见 仁 见 智 。 


译 者 简介 及 联系 方式 


李 苏 南 ( 笔 名 苏 南 ) ， 毕 业 于 华北 电力 大 学 。 浪 迹 京城 十 余 载 ， 地 处 中 关 村 人 篇 北 。 目 前 在 国内 某 知 名 金融 投资 公司 做 构架 相关 的 工作 。 如 果 您 对 我 感 兴趣 ， 欢 迎 通 过 国内 第 一 家 Hack 语 言 中 文 网 站 
(http://www.hacklang.org.cn) 找到 我 的 联系 方式 。 


由 于 经 验 不 足 等 原因 ， 本 书 的 翻译 过 程 不 可 避免 地 出 现 一 些 纶 漏 。 如 果 您 有 疑问 ， 欢 迎 访问 http://www.hacklang.org.cn 以 及 http://www.hhvm.com.cn， 参 与 我 们 的 在 线 讨 论 和 互动 。 同 时 ， 本 书 的 相关 源 
码 及 勘误 表 ， 也 可 以 在 上 述 网 站 上 找到 。 


在 本 书 出 版 时 ， 实 际 的 版 本 内 容 与 书 中 相 比 ， 会 不 可 避免 地 发 生变 化 。 我 会 在 网 站 上 及 时 地 更 新 和 调整 。 同 时 ， 本 书 中 没有 提 及 的 “HHVM 安 装 过 程 ”以 及 “支持 Hack 语 言 的 编程 工具 ”等 内 容 ， 也 会 
在 网 站 中 进行 补充 。 


欢迎 加 入 我 们 的 讨论 。 与 大 家 一 起 传播 Hack 语 言 ， 让 更 多 的 人 体会 到 “更 淋 注 尽 致 的 编程 体验 ”。 
苏 南 


2016 年 12 月 


作者 介绍 


Owen Yamauchi 是 一 名 在 Facebook 工 作 的 软件 工程 师 ， 他 在 HHVM 团 队 工 作 。 在 2009 年 加 入 Facebook 之 前 ， 他 曾经 在 VMware 和 苹果 公司 实习 。Owen 在 比利时 长 大 ， 并 且 在 卡耐基 梅 隆 大 学 获得 了 计算 机 


科学 学 士 学 位 。 


封面 介绍 


本 书 的 封面 动物 是 一 只 灰色 的 狐狸 (Urocyon cinereoargenteus) ， 它 被 认为 在 最 原始 的 犬 科 动物 之 间 ， 属 于 两 种 唯一 存活 的 灰 狐 属 动物 族 类 之 一 。 另 外 一 种 是 海峡 岛 狐 (the Channel Island fox) 。 灰 狐 是 
一 种 杂食 动物 ， 在 加 拿 大 南部 到 南美 洲 的 北部 区 域 都 有 分 布 。 根 据 生活 区 域 的 不 同 ， 它 的 主要 食物 也 不 同 ， 主 要 有 东部 棉 尾 免 (the eastern cottontail) 、 和 鼠 类 、 鸟 类 、 咕 齿 目 动物 以 及 野 免 。 在 美国 西部 的 一 
些 区 域 ， 灰 狐 主要 以 昆虫 和 植物 为 生 。 所 有 的 灰 狐 都 以 水 果 作 为 日 常 饮食 。 

灰 狐 以 斑 白 的 上 半身 、 黑 色 尾 尖 以 及 强壮 的 脖子 而 闻名 。 公 灰 狐 和 母 灰 狐 非常 相似 ， 只 是 母 灰 狐 的 个 头 会 稍稍 小 一 些 。 灰 狐 包括 尾部 的 长 度 一 般 为 76 到 112.5 厘 米 (29.9 到 44.3 英 寸 ) ， 尾 部 的 长 度 一 般 
占 27.5 到 44.3 厘 米 (10.8 到 17.4 英 寸 ) 的 长 度 。 个 体重 量 一 般 在 3.6 到 7 公斤 (7.9 到 15.4 磅 ) 。 

灰 狐 非常 善于 爬 桂 ， 它 们 经 常 和 同 是 犬 科 动物 的 亚洲 获 (the Asian raccoon dog) 分 享 这 种 技能 。 这 是 它 逃 避 许 多 食 内 动物 ( 家 狗 或 者 狼 ) 的 策略 ， 来 得 到 树木 周围 的 食物 资源 。 它 非常 善于 使 用 这 种 能 
力 ， 在 逐步 的 进化 中 ， 他 可 以 非常 容易 地 用 它 锋 利 的 爪子 假 上 18 米 高 没有 枝叶 的 树干 。 它 通过 从 一 个 树枝 跳 到 另外 一 个 树枝 ， 或 者 缓慢 地 倒退 攀 拒 下 树 。 灰 狐 是 夜间 活动 的 ， 它 的 巢穴 一 般 建 于 空心 树 或 者 
废弃 的 树桩 里 面 。 有 的 时 候 ， 它 的 集 穴 会 离 地 面 30 英 尺 高 [1。 

灰 狐 是 一 夫 一 妻 制 ， 在 北方 常 在 三 月 上 旬 进 行 交配 ， 而 在 南方 一 般 在 二 月 份 。 妊 娠 时 间 会 持续 53 天 ， 一 般 产 仔 数量 为 1 到 7 只 。 在 三 个 月 大 的 时 候 ， 幼 岂 开 始 和 父母 一 起 打猎 。 四 个 月 大 的 时 候 ， 幼 患 可 
以 自己 独立 砚 食 。 在 秋天 的 时 候 ， 年 轻 的 个 体 将 离开 它们 的 家 庭 组 织 ， 到 达 性 成 熟 。 


O 〇 ”Reilly 的 很 多 封面 动物 都 濒临 灭绝 ， 它 们 对 世界 非常 重要 。 你 可 以 访问 animals.oreilly.com 来 了 解 更 多 你 可 以 做 的 事情 。 


封面 图 片 来 自 Wood 的 Animate Creation。 


站 1 英尺 =0.3048 米 


序 


2012 年 ， 我 和 Alok Menghrajan 开 始 了 一 项 叫做 “strict-mode” 的 新 工作 项 目 。 简 而 言 之 ， 项 目的 目标 就 是 在 HHVM 的 基础 之 上 构建 一 个 静态 类 型 版 本 的 PHP。 


从 此 以 后 ， 我 着 迷 于 该 项 目 所 取得 的 成 功 ， 这 个 项 目 后 来 演变 成 大 家 所 熟知 的 Hack 语 言 。 这 个 项 目 从 最 开始 的 类 型 检查 器 演变 成 为 一 门 成 熟 的 编程 语言 ， 并 且 有 行业 级 别 的 工具 做 后 盾 支撑 。 


回 望 来 路 ， 当 第 一 次 向 HHVM 团 队 表达 我 们 对 项 目的 想法 的 时 候 ， 我 有 足够 的 理由 相信 他 们 认为 我 们 疯 了 。 但 是 最 终 ， 我 们 还 是 成 功 地 说 服 了 他 们 ， 让 他 们 加 入 了 我 们 的 冒险 之 旅 。 


在 2012 年 6 月 底 的 时 候 ，Facebook 网 站 首次 将 Hack 语 言 部 署 应 用 到 产品 中 。 就 这 样 ， 没 有 任何 管理 上 的 认可 ， 也 没有 任何 形式 的 过 程 ，Facebook 在 生产 中 有 了 一 门 新 的 编程 语言 。 


就 在 这 个 时 候 ， 我 非常 期 待 有 人 能 够 及 时 叫 停 我 们 ， 然 而 这 样 的 情况 却 从 未 发 生 。 


很 多 工程 师 跟随 着 我 们 的 脚步 。 在 我 们 知道 之 前 ，Facebook 内 部 大 多 数 新 的 代码 都 使 用 Hack 语 言 进行 编写 。 于 是 我 们 决定 把 剩余 的 PHP 代 码 库 自动 转 为 Hack 语 言 的 代码 。 我 们 从 动态 变量 类 型 的 PHP 
到 静态 变量 类 型 的 Hack 语 言 ， 转 化 了 巨大 规模 (上 亿 行 ) 的 代码 。 


这 个 过 程 是 极 具 挑战 性 的 ， 挑 战 主要 来 自 于 我 们 所 采用 的 类 型 检查 器 的 C/S 技 术 框架 ， 因 为 PHP 开 发 人 员 已 经 习惯 于 一 个 快速 编辑 /刷新 的 周期 ， 所 以 我 们 希望 类 型 检查 器 有 个 快速 的 响应 时 间 。 这 就 是 
我 们 使 用 Hack 语 言 类 型 检查 服务 器 的 原因 : 一 个 背后 默默 支撑 着 类 型 信息 的 守护 进程 。 当 然 ， 最 为 棘手 的 问题 是 如 何 保持 与 文件 系统 相 一 致 的 服务 器 状态 。 


为 了 使 类 型 检查 服务 器 更 稳定 地 运行 ， 我 们 度 过 了 无 数 个 不 眠 的 夜晚 。 正 是 如 此 ， 也 造就 了 Hack 语 言 如 此 不 平凡 的 今天 。 在 面临 海量 代码 更 新 的 时 候 ， 类 型 检查 器 的 响应 时 间 几 乎 是 瞬时 的 ( 快 到 可 以 
自动 完成 ) 。 


我 非常 高 兴 ， 现 在 有 了 这 本 Hack 和 HHVM 方 面 的 权威 指导 书 。Owen 在 此 做 了 非常 卓越 的 工作 ， 甚 至 关于 Hack 语 言 的 微妙 之 处 ， 他 都 做 了 详细 的 解释 。 当 然 ， 还 有 其 他 一 些 需要 你 在 Hack/HHVM 的 
调试 及 生产 过 程 中 知晓 的 注意 事项 。 


希望 你 能 够 享受 使 用 Hack 和 HHVM 的 乐趣 ! 


Julien Verlaguet，Hack 语 言 之 父 


囊 


前 


在 Facebook 公 司 的 大 部 分 发 展 历程 中 ， 每 隔 几 个 月 就 会 举办 “黑客 马拉松 (hackathons) ”活动 ， 活 动 的 目的 在 于 鼓励 工程 师 们 碰撞 出 好 的 想法 ， 而 这 些 好 的 想法 并 不 是 和 他 们 的 日 常 工作 相关 的 ， 
他 们 自由 组 队 ， 然 后 在 一 两 天 的 时 间 内 做 出 一 些 非常 有 意思 的 事情 。 


在 2007 年 11 月 的 一 次 “黑客 马拉松 ”活动 上 ， 诞 生 了 一 个 非常 有 意思 的 实验 : 一 个 工具 能 够 将 PHP 程 序 转化 为 C++ 程序 ， 然 后 还 能 够 用 C+ + 编译 器 进行 编译 。 想 法 是 C+ + 程序 将 会 比 PHP 原 生 的 程序 
运行 起 来 快 很 多 ， 因 为 它 可 以 得 益 于 多 年 以 来 对 C++ 编译 器 的 大 量 优化 工作 。 


对 于 Facebook 来 说 ， 这 种 可 能 性 是 非常 有 趣 的 ， 因 为 公司 增加 了 大 量 新 的 用 户 ， 而 支持 更 多 新 的 用 户 需 要 耗费 大 量 的 CPU 运算 周期 。 所 以 当 你 耗 尽 所 有 可 用 的 CPU 运算 周期 后 ， 除 非 你 耗费 大 量 财力 
购买 更 多 的 CPU， 用 来 支持 日 益 增多 的 用 户 所 带 来 的 CPU 运算 能 力 的 需求 ， 否 则 你 必须 寻找 一 个 方法 来 降低 每 个 用 户 的 CPU 消耗 。 由 于 Facebook 整 个 网 站 的 前 端 都 是 用 PHP 语 言 编 写 的 ， 所 以 任何 使 PHP 
代码 耗费 更 少 CPU 运算 周期 的 新 技术 都 受到 欢迎 。 


在 接 下 来 的 7 年 时 间 里 ， 这 个 项 目的 发 展 远 远 超出 了 最 开始 在 “黑客 马拉松 ”中 的 起 点 。PHP 到 C++ 的 转换 器 称 为 HPHPc， 在 2009 年 的 时 候 它 成 为 支撑 Fackbook 网 页 业务 唯一 的 服务 器 端 引擎 。 在 
2010 年 年 初 ， 它 以 “HipHop for PHP” 的 名 字 开 源 了 。 然 后 从 2010 年 起 ， 一 个 全 新 的 方法 用 来 执行 一 一 即时 编译 为 机 器 代码 ， 并 没有 C++ 牵扯 其 中 一 一 脱胎 换 骨 于 HPHPc 的 代码 库 ， 并 最 终 取 代 它 。 这 
个 即时 的 编辑 器 称 为 “HipHop 虚 拟 机 ”， 简 称 为 HHVM ， 并 且 在 2013 年 的 早期 彻底 取代 了 Facebook 的 网 站 服务 器 集群 。 早 期 的 PHP 到 C++ 的 转换 器 消失 了 ， 它 没有 在 任何 地 方 进行 部 署 ， 同 时 它 的 代码 
都 被 删除 了 。 


而 Hack 的 起 源 是 完全 分 开 的 ， 其 根源 在 于 试图 在 PHP 中 使 用 静态 分 析 以 自动 探测 潜在 的 安全 漏洞 的 一 个 项 目 。 很 快 ， 事 实证 明 ，PHP 的 本 质 使 得 它 在 非常 有 用 的 静态 分 析 方 面 很 难 有 所 进展 。 于 是 “ 严 
格 模式 (strictmode) ”的 想法 就 诞生 了 。 对 PHP 进 行 修改 ， 增 加 一 些 新 的 特性 ， 比 如 引用 、 删 除 和 添加 一 个 补充 的 复杂 类 型 系统 。PHP 代 码 的 作者 可 以 自由 选择 是 否 使 用 严格 模式 ， 在 保持 完整 的 互 操作 
性 同时 ， 获 得 更 加 强大 的 代码 检查 能 力 。 


出 


Hack 的 方向 从 那 时 开始 就 作为 基于 PHP 的 类 型 系统 掩盖 了 其 本 质 。 它 在 构建 Hack 编 码 的 道路 上 获得 了 很 多 有 重大 影响 的 新 特性 ， 比 如 异步 函数 。 它 添加 了 很 多 包括 集合 在 内 的 新 特性 ， 使 得 类 型 系统 
更 加 强大 。 本 质 上 来 说 ， 它 是 一 门 和 PHP 不 同 的 新 语言 ， 它 已 经 在 编程 语言 方面 取得 了 自己 的 新 位 置 。 


以 上 就 是 Hack 的 发 展 历程 ， 目 前 Hack 是 一 门 现代 化 的 动态 编程 语言 ， 它 拥有 和 鲁 棒 的 静态 类 型 检查 能 力 ， 在 HHVM 上 执行 。HHVM 是 一 个 和 PHP 无 颖 兼容 且 具 有 互 操作 性 的 实时 编译 运行 时 引擎 。 


什么 是 Hack 和 HHVM 


Hack 和 HHVM 是 紧密 联系 在 一 起 的 ， 所 以 对 于 这 些 术语 到 底 指 代 的 是 什么 会 有 一 些 混乱 。 


Hack 是 一 门 编程 语言 。 它 基于 PHP， 继 承 了 PHP 中 的 很 多 语法 ， 并 且 完 全 可 以 和 PHP 进 行 互 操作 。 然 而 ， 很 可 能 有 人 会 认为 Hack 只 是 在 PHP 的 基础 上 略 加 了 装饰 修改 。Hack 最 核心 的 特色 是 鲁 棒 的 静 
态 类 型 检查 ， 这 已 经 足够 把 Hack 作 为 一 门 编程 语言 和 PHP 区 分 开 了 。 对 于 现在 已 经 从 事 已 有 PHP 代 码 库 开发 方面 工作 的 开发 者 来 说 ， 这 是 非常 有 益 的 。 在 这 种 情形 下 ， 将 会 给 这 些 开 发 者 很 多 的 启迪 ， 当 
然 ， 对 于 新 项 目的 底层 开发 也 是 一 个 非常 不 错 的 选择 。 


除了 静态 类 型 检查 外 ，Hack 还 拥有 PHP 没 有 的 很 多 项 新 特性 ， 本 书 将 对 这 些 新 特性 进行 阐述 : 异步 函数 、XHP 等 。 出 于 解决 一 些 粗 糙 边 界 问题 的 目的 ，Hack 也 故意 缺失 了 对 一 些 PHP 特 性 的 支持 。 


HHVM 是 一 个 执行 引擎 ， 它 同时 支持 PHP 和 Hack。 它 让 两 种 语言 可 以 互 操作 : PHP 书 写 的 代码 能 够 调用 Hack 代 码 ， 反 之 亦 然 。 当 执行 PHP 的 时 候 ， 它 的 目标 在 于 对 PHP.net 提 供 的 PHP 标 准 解释 器 进 
行 蔡 换 。 本 书 中 有 些 章节 的 内 容 是 关于 HHVM 的 : 如 何 配置 并 部 署 它 ， 如 何 使 用 它 调试 和 配置 代码 。 


最 后 ， 我 们 要 介绍 的 就 是 从 HHVM 中 分 离 出 来 的 Hack 类 型 检查 器 : 这 是 一 个 能 够 分 析 Hack 代 码 (而 不 是 PHP 代 码 ) 然后 报告 类 型 错误 的 程序 。 在 它 能 够 接受 的 代码 方面 ， 类 型 检查 器 目前 要 比 HHVM 
严格 一 些 。 当 然 ， 在 未 来 的 发 行 版 本 中 ，HHVM 应 该 比 类 型 检查 器 更 加 严格 。 目 前 ， 除 了 你 在 命令 行 里 面 启动 它 的 命令 “hh_client” 外 ， 类 型 检查 器 还 没有 个 定型 的 名 字 ， 我 更 倾向 于 叫 它 “Hack 类 型 检 
查 器 ” (Hack typechecker) 或 者 就 叫做 “类 型 检查 器 ” (typechecker) 。 


到 目前 为 止 ，HHVM 是 运行 Hack 的 唯一 执行 引擎 ， 这 也 是 有 时 它们 会 混为一谈 的 原因 。 


本 书 读者 对 象 


本 书 适合 那些 已 经 对 编程 有 一 定 基础 的 读者 。 这 里 并 没有 花费 时 间 解 释 很 多 编程 语言 里 面 常见 的 概念 。 例 如 控制 流 、 数 据 类 型 、 函 数 、 面 向 对 象 编程 等 。 


Hack 派 生 于 PHP， 本 书 不 会 特别 解释 PHP 中 常见 的 语法 ， 除 非 Hack 里 面相 关 的 语法 知识 点 与 之 不 同 。 所 以 有 PHP 的 知识 基础 将 会 非常 有 用 。 如 果 你 从 来 没有 使 用 过 PHP， 但 是 有 其 他 编程 语言 的 相关 
经 验 ， 那 么 你 仍然 能 够 读 懂 本 书 里 面 的 大 部 分 代码 。 语 法 知识 点 都 是 非常 易于 理解 的 。 


如 果 你 拥有 PHP 相 关 经 验 ， 但 是 从 未 工作 在 一 个 复杂 、 高 负载 的 PHP 网 站 环境 中 ， 你 也 不 必 担 心 这 里 有 什么 你 看 不 懂 的 。 无 论 你 的 代码 是 简单 独立 运行 的 小 脚本 ， 还 是 数 以 百 万 行 级 别 像 Facebook 一 样 
的 大 型 Web 应 用 ，Hack 对 于 任何 规模 的 代码 库 都 大 有 神 益 。 


这 里 有 一 些 材料 假设 你 对 传统 的 Web 应 用 已 经 熟悉 ， 例 如 关系 数据 库 查 询 、 使 用 memcached ( 见 第 6 章 ) 和 生成 HTML ( 见 第 7 章 ) 。 如 果 它们 和 你 不 相关 ， 那 么 你 可 以 跳 过 这 些 章节 。 但 是 事实 上 ， 
对 这 些 章节 的 理解 并 不 需要 什么 特别 的 知识 ， 哪 怕 是 小 的 基础 网 站 应 用 的 开发 经 验 。 


我 希望 本 书 并 不 仅仅 用 来 解释 事物 具体 是 什么 的 ， 而 且 希 望 介绍 它 是 怎样 的 运作 原理 。 程 序 语言 设计 是 一 个 很 困难 的 问题 。 它 本 质 上 是 一 门 对 上 百 个 可 能 的 方案 统一 进行 权衡 的 艺术 ， 同 时 它 还 受 向 
兼容 的 相关 内 容 的 制约 ，Hack 也 不 例外 。 所 以 如 果 你 对 “一 门 程序 语言 如 何 通过 一 系列 不 同 寻常 的 限制 来 成 就 未 来 ”这 个 案例 学 习 感 兴趣 ， 那 么 本 书 将 会 提供 你 所 需要 的 内 容 。 


mm 


在 Hack 和 HHVM 设 计 的 背后 存在 着 一 些 理念 。 这 些 理念 可 以 帮助 你 理解 事物 的 运转 方式 。 


程序 类 型 


这 里 有 个 单独 的 观察 程序 用 于 指引 HHVM 优 化 和 执行 代码 的 方式 ， 还 指引 Hack 验 证 它 的 方式 。 它 就 是 隐藏 在 大 多 数 动态 语言 程序 背后 的 一 个 静态 类 型 的 程序 。 


看 一 下 如 下 代码 ， 这 段 代码 在 PHP 和 Hack 下 都 可 以 正常 运行 : 


for ($i = 0; $i < 10; $i++) { 
echo $i + 100; 
} 


虽然 没有 明确 进行 说 明 陈述 ， 但 是 对 于 任何 读者 来 说 ， 很 明显 $j 总 是 个 整数 。 用 计算 机 术语 来 说 ，$i 是 单 态 (monomorphic) 的 : 它 只 有 一 个 类 型 。 类 型 检查 器 将 会 利用 这 个 属性 来 验证 表达 


式 “$i+100” 是 否 有 意义 。 一 个 执行 引擎 也 会 利用 这 个 属性 把 “$i+100” 编 译 为 高 效 机 器 码 ， 来 做 这 个 加 法 运算 。 


循环 变量 看 起 来 似乎 是 个 平常 的 例子 ， 但 事实 证 明 ， 在 现实 世界 的 PHP 代 码 库 中 ， 大 多 数 的 值 都 是 单 态 的 。 这 造成 了 一 种 直觉 ， 对 于 一 个 值 ， 如 果 不 知道 它 的 类 型 ， 你 就 不 能 做 太 多 的 事情 。 比 如 在 它 
上 面 做 算术 运算 ， 对 它 做 索引 ， 调 用 它 上 面 的 方法 等 。 甚 至 在 动态 类 型 语言 中 ， 大 多 数 的 代码 在 使 用 它 做 任何 事情 之 前 ， 并 不 会 检查 它 的 类 型 ， 这 就 意味 着 这 里 有 关于 值 类 型 的 隐藏 设 定 。 如 果 运行 的 大 多 
数 代码 不 存在 运行 时 类 型 错误 ， 那 么 大 多 数 的 时 候 这 些 隐藏 设 定 也 必须 成 立 。 


HHVM 的 方法 是 假设 这 个 观点 成 立 ， 并 且 相 应 地 编译 PHP 和 Hack 为 机 器 码 。 因 为 它 运行 的 同时 进行 程序 的 编译 ， 它 知道 将 要 编译 的 每 条 代码 的 逻辑 流向 。 它 将 生成 机 器 代码 并 假定 这 些 类 型 : 在 前 面 所 
示 的 范例 代码 中 ， 当 编译 表达 式 $i+100 时 ，HHVM 将 看 到 $i 是 一 个 整数 ， 然 后 使 用 单条 加 法 硬件 指令 来 做 这 项 相 加 操作 。 


同时 ，Hack 的 目的 在 于 使 隐藏 的 静态 类 型 程序 显示 出 来 。 它 使 一 些 类 型 进行 显 式 的 标 通 过 标注 使 一 些 类 型 变 成 显 式 的 ， 然 后 使 用 类 型 推理 得 到 余下 的 类 型 信息 。 现 在 的 理念 就 是 ，Hack 并 不 显 式 地 限 
制 已 经 存在 的 PHP 程 序 ， 而 是 对 PHP 程 序 已 经 显露 出 来 的 行为 进行 鲁 棒 的 静态 分 析 。 


这 里 有 一 点 值得 重复 一 下 : Hack 的 静态 类 型 并 不 会 带 给 你 一 个 不 同 的 编程 风格 。 这 门 语言 用 来 给 你 已 经 写 好 的 程序 一 个 更 好 的 诠释 方式 。 


Hack 起 源 于 一 个 数 以 百 万 行 计 的 PHP 代 码 库 。 不 管 这 两 种 语言 之 间 有 多 么 相似 ， 这 里 都 没有 什么 办 法 能 够 一 下 子 把 如 此 大 规模 的 代码 库 从 一 种 语言 迁移 到 另外 一 种 语言 ， 所 以 Hack 采 用 了 从 PHP 逐 步 
迁移 的 路 线 。Hack 可 以 使 用 以 PHP 编 写 的 函数 和 类 ， 反 之 亦 然 。 对 于 Hack 的 每 个 特性 ， 无 论 是 否 使 用 它 的 代码 ， 这 里 都 有 无 颖 对 接 进行 交互 的 方法 。 


另外 ， 标 准 的 Hack/HHVM 发 行 版 有 自动 从 PHP 到 Hack 迁 移 的 工具 ， 它 还 包含 一 个 工具 用 于 把 Hack 代 码 编译 为 PHP 代 码 。 这 主要 是 为 了 方便 一 些 类 库 的 作者 迁移 到 Hack 上 ， 同 时 为 非 HHVM 用 户 保 持 
一 个 使 用 其 代码 的 通道 。 这 些 工具 代码 将 在 第 10 章 中 详细 描述 。 


而 HHVM 致 力 于 能 够 和 标准 的 PHP 解 释 器 一 样 运行 PHP 代 码 。 迁 移 PHP 代 码 库 到 Hack 的 第 一 步 就 是 要 在 HHVM 上 运行 PHP 代 码 。 在 这 一 步骤 中 ， 唯 一 重要 的 必要 代码 变更 就 是 围绕 扩展 的 ， 并 不 是 所 
有 的 PHP 和 Zend 扩 展 都 兼容 HHVM。 这 里 不 应 该 由 于 核心 语言 的 不 同行 为 而 导致 扩展 有 所 变化 。 


除去 它 的 本 源 因素 ， 对 于 开始 一 个 新 的 项 目 ，Hack 毫 无 疑问 是 个 非常 棒 的 选择 。 事 实 上 ， 你 会 以 这 样 的 方式 从 Hack 中 获得 最 大 的 益处 : 当代 码 库 100% 是 纯正 的 Hack 代 码 时 ， 这 门 语言 会 发 挥 它 的 极 
致 。 


本 书 是 如 何 组 织 的 


Hack 的 核心 功能 是 静态 类 型 检查 。 它 广泛 涉及 了 Hack 的 所 有 其 他 特性 ， 是 Hack 和 PHP 最 显著 的 区 别 。 本 书 第 1 章 就 详细 地 对 本 话题 展开 了 阐述 。 本 书 所 有 其 他 章节 的 内 容 都 依赖 于 对 本 章 内 容 的 理 
解 ， 所 以 如 果 以 前 你 没有 接触 过 Hack， 我 强烈 建议 你 仔细 阅读 第 1 章 的 内 容 。 第 2 章 进 行 了 补充 ， 该 章 主要 讨论 了 在 Hack 的 类 型 体系 中 非常 有 趣 的 部 分 。 


Hack 其 余 的 特性 彼此 间 几 乎 都 是 正 交 的 。 第 3 章 主 要 解释 了 Hack 的 一 些小 特性 。 第 4 章 展示 了 一 些 在 Hack 中 并 不 存在 的 PHP 特 性 以 及 这 样 的 原因 。 第 5 章 解释 了 如 何 及 为 什么 使 用 Hack 的 集合 类 。 第 6 
章 主要 解释 了 Hack 的 多 任务 支持 。 第 7 章 主 要 解释 Hack 中 更 加 稳健 、 更 加 安全 地 创建 HTML 的 语法 和 库 。 


第 8 章 主 要 涉及 设置 、 配 置 、 部 署 和 对 HHVM 的 监控 问题 。 第 9 章 涉 及 HHVM 的 交互 式 调试 器 hphpd。 最 后 ， 第 10 章 主要 探索 了 一 些 编写 Hack 代 码 时 所 需要 的 工具 ， 包 括 从 PHP 到 Hack 的 迁移 工具 和 一 
个 交互 式 调试 器 。 


版 本 


本 书 使 用 Hack 3.6 和 HHVM 3.6， 这 个 版 本 于 2015 年 3 月 11 日 发 布 。 (HHVM 和 Hack 的 类 型 检查 器 存在 于 同一 个 代码 库 中 ， 它 们 包含 在 同一 个 代码 发 行 包 内 。) 当 你 读 到 这 些 内 容 的 时 候 ， 应 该 会 有 更 
新 的 版 本 可 用 。 然 而 ，3.6 版 本 将 会 是 个 长 期 支持 的 版 本 。 会 在 发 布 的 48 周 后 修复 安全 问题 及 bug。 


HHVM 3.6 实 现 了 PHP 5.6 的 语义 1。 它 支持 PHP 5.6 中 所 有 的 新 特性 ， 包 括 常 量 scalar 表 达 式 、 可 变 参数 函数 、 取 军 操 作 符 等 。 这 些 新 的 特性 在 Hack 3.6 上 也 存在 。 通 常 来 说 ， 当 一 个 新 版 本 的 PHP 发 
布 时 ，HHVM 都 会 为 Hack 代 码 和 PHP 代 码 及 时 增加 对 新 特性 及 语义 的 支持 。 


本 书 约定 


本 书 中 使 用 以 下 排版 约定 : 


斜体 


表明 新 术语 、 网 址 、 电 子 邮件 地 址 、 文 件 名 和 文件 扩展 名 。 


等 宽 字体 


于 代码 清单 以 及 在 正文 中 引用 程序 元 素 ， 如 变量 或 函数 名 、 数 据 库 、 数 据 类 型 、 环 境 变量 、 语 句 和 关键 字 。 


等 宽 粗 体 


显示 用 户 应 该 输入 的 命令 或 其 他 文本 。 


名 这 个 元 素 表 示 提示 或 建议 。 


区 过 个 元 素 表示 一 般 注解。 


Safari@ 图 书 在 线 


Safari Books Online 是 一 个 随 需 而 变 的 数字 图 书馆 ， 在 技术 和 商业 方面 以 书 和 视频 的 形式 ， 从 世界 领先 的 作者 那里 发 布 专业 的 内 容 。 


专业 技术 人 员 、 软 件 开发 人 员 、 网 页 设计 人 员 、 商 业 和 创新 型 人 才 使 用 Safari 图 书 在 线 ， 用 于 科研 、 解 决 问题 、 学 习 和 资格 培训 。 


Safari 图 书 在 线 为 企业 、 政 府 、 教 育 机 构 及 个 人 提供 一 系列 计划 和 定价 服务 。 


会 员 可 以 通过 一 个 可 全 面 搜索 的 数据 库 ， 访 问 数 以 干 计 的 图 书 、 培 训 视 频 以 及 出 版 前 的 手稿 。 这 些 内 容 来 自 数 以 百 计 的 出 版 社 ， 如 O 擒 eilly Media、Prentice Hall Professional、Addison-Wesley 
Professional、 Microsoft Press、Sams、Que、Peachpit Press、Focal Press、Cisco Press、 John Wiley & Sons、 Syngress、Morgan Kauf-mann、|IBM Redbooks、Packt、Adobe Press、FT 


Press、Apress、Manning、New Riders、McGraw-Hill、Jones & Bartlett、Course Technology 等 。 为 了 获得 更 多 关于 我 们 的 信息 ， 请 访问 我 们 的 网 址 。 


如 何 联系 我 们 


美国 : 


O’ Reilly Media, Inc. 


1005 Gravenstein Highway North 
Sebastopol，CA 95472 


中 国 : 


北京 市 西城 区 西直门 南大 街 2 号 成 铬 大 厦 C 座 807 室 (100035) 


奥 莱 利 技术 咨询 (北京 ) 有 限 公司 


我 们 为 本 书 提供 了 网 页 ， 该 网 页 上 面 列 出 了 勘误 表 、 范 例 和 任何 其 他 附加 的 信息 。 您 可 以 访问 如 下 网 页 获得 : 


http://bit.ly/hack-and-hhvm 
要 询问 技术 问题 或 对 本 书 提出 建议 ， 请 发 送 电子 邮件 至 : 


bookquestions@oreilly.com 


要 获得 更 多 关于 我 们 的 书籍 、 会 议 、 资 源 中 心 和 O'Reilly 网 络 的 信息 ， 请 参见 我 们 的 网 站 : 
http://www.oreilly.com.cn 


http://www.oreilly.com 


致谢 


首先 ， 没 有 多 年 来 奋战 在 HipHop、HHVM 和 Hack 的 所 有 同事 的 共同 努力 ， 本 书 显然 是 不 会 存在 的 。 这 其 中 包含 Facebook 的 现 员工 和 前 员工 以 及 开源 社区 的 成 员 ， 这 里 不 
他 们 的 不 懈 努 力 、 无 私 奉献 ，Hack 和 HHVM 才 能 有 今天 的 成 绩 。 


列举 他 们 的 名 字 。 正 是 


这 些 项 目 不 仅 代表 着 一 个 巨大 的 成 果 ， 它 们 还 是 重大 风险 的 回报 。 没 有 任何 一 个 项 目 在 其 寝 宰 期 内 是 肯定 会 获得 成 功 的 。 它 们 都 必须 花费 一 定 的 时 间 来 为 自己 的 继续 存在 而 奋斗 。 从 经 验 上 来 看 ， 我 最 
了 解 的 故事 当 属 HHVM 了 。 在 两 年 的 最 好 时 间 内 ，HHVM 团 队 努 力 提升 HHVM 的 性 能 ， 使 其 和 HipHop 能 够 平起平坐 。 他 们 知道 ， 如 果 不 能 成 功 ， 他 们 将 失去 这 项 工作 中 的 一 切 ， 工 程 师 和 管理 团队 尽管 冒 
着 这 样 的 风险 ， 但 仍 努力 推动 项 目前 进 ， 这 点 特别 值得 肯定 。 多 年 来 耗费 自己 和 他 人 的 职业 生涯 在 这 项 有 待 探寻 的 事情 上 来 是 非常 不 易 的 。 在 这 里 ， 特 别 感谢 如 下 缔造 者 : 来 自 HipHop 的 Haiping 
Zhao，HHVM 团 队 的 Keith Adams、Jason Evans 和 Drew Paroski， 以 及 来 自 Hack 团 队 的 Julien Verlaguet。 


现在 ， 我 非常 感激 能 够 有 机 会 写 这 本 书 。 我 认为 不 会 有 很 多 公司 或 者 团队 会 乐于 让 他 们 的 工程 师 花费 7 个 月 的 时 间 来 写 书 ， 而 不 是 编写 软件 。 在 写 书 这 件 事情 上 ， 一 些 人 对 本 书 也 有 很 大 的 帮助 。 按 照 姓 
名 字母 排序 ， 他 们 是 Alma Chao、Todd Gascon、Joel Marcey、James Pearce、Joel Pobar 和 Paul Tarjan。 


非常 感谢 Hack 和 HHVM 的 团队 成 员 ， 正 是 他 们 审阅 了 本 书 的 初稿 。 按 照 姓名 字母 排序 ， 他 们 是 Fred Emmott、Bill Fumerola、Eugene Letuchy、Alex Malyshev、Joel Marcey、Jez Ng、Jan 
Oravec、Dwayne Reeves、Julien Verlaguet、Josh Watzman。 本 书 由 于 他 们 的 反馈 而 迅速 得 以 改进 。 书 里 如 果 有 什么 错误 ， 那 也 是 我 的 问题 ， 与 他 们 无 关 。 


[由 相应 的 次 要 版 本 号 仅仅 是 个 巧合 。 一 般 ，HHVM/Hack 和 PHP 版 本 号 之 间 没 有 任何 联系 。 


类 型 检查 器 是 Hack 语 言 的 标志 特性 ， 它 对 Hack 程 序 静 态 地 进行 分 析 (不 用 运行 它们 ) ， 并 且 能 够 检查 很 多 种 错误 。 这 就 能 够 在 程序 开发 初期 尽量 避免 bug， 并 且 使 程序 更 容易 阅读 和 理解 。 为 了 增强 类 
型 检查 器 的 能 力 ，Hack 语 言 允许 编程 人 员 显 式 地 在 程序 体 中 标注 某 些 变量 值 的 类 型 ， 比 如 函数 参数 、 函 数 返 回 值 和 属性 值 ， 类 型 检查 器 将 推断 出 剩 下 的 内 容 。 


关于 编程 语言 静态 类 型 化 还 是 动态 类 型 化 的 争论 在 程序 员 中 一 直 都 存在 。 争 论 的 焦点 通常 表现 为 静态 类 型 的 鲁 棒 性 和 动态 类 型 的 灵活 性 之 间 的 选择 。Hack 语 言 的 哲学 拒绝 认同 这 个 虚假 的 二 分 法 论断 。 
Hack 语 言 作为 一 门 动态 类 型 的 语言 ， 在 保留 PHP 的 灵活 、 可 快速 开发 特性 的 同时 ， 增 加 了 一 层 强 健 且 精妙 的 类 型 检查 器 。 


在 本 章 ， 我 们 将 了 解 为 什么 需要 使 用 类 型 检查 器 ， 怎 么 使 用 类 型 检查 器 ， 以 及 如 何 给 变量 标注 类 型 。 


1.1 为 什么 使 用 类 型 检查 器 


关于 对 Hack 语 言 类 型 检查 器 赞同 的 观点 ， 听 起 来 和 对 静态 类 型 语言 赞同 的 观点 非常 接近 。 类 型 检查 器 能 够 在 不 运行 程序 体 本 身 的 情况 下 ， 对 错误 进行 查找 和 检查 。 所 以 在 测试 过 程 中 ， 即 使 不 运行 代 
码 ， 它 也 能 够 捕获 问题 所 在 。 正 是 因为 不 需要 去 执行 程序 体 ， 所 以 能 够 在 程序 开发 的 早期 及 时 地 捕获 错误 ， 这 将 大 幅度 地 节约 开发 时 间 。 静 态 分 析 的 能 力 能 够 确保 在 模块 边界 没有 破损 ， 这 使 代码 重 构 变 得 
更 加 简单 。 


在 最 经 典 的 争论 中 ， 所 谓 的 缺点 总 是 伴随 着 一 些 能 够 拖 慢 开发 速度 的 特征 。 在 能 够 正式 运行 程序 之 前 ， 你 不 得 不 花费 时 间 等 待 程序 体 进行 编译 。 这 依赖 于 程序 所 使 用 的 编程 语言 及 程序 体 本 身 的 大 小 。 
同时 ， 你 必须 在 程序 体内 部 给 出 所 有 变量 的 类 型 ， 这 将 使 你 的 程序 体 更 加 宛 长 并 且 难 以 维护 。 


然而 这 些 诉 病 在 Hack 语 言 中 并 不 存在 ， 这 基于 如 下 两 点 原因 。 第 一 点 ， 类 型 检查 器 被 设计 成 及 时 反馈 的 ， 即 使 在 非常 大 的 代码 库 内 ， 也 可 以 做 到 及 时 反馈 。 它 使 用 的 是 “客户 端 /服务 端 ” 模 型 : 类 型 
俭 查 的 服务 端 在 后 台 运 行 ， 并 且 时 刻 在 监控 文件 系统 的 变化 。 当 你 编辑 一 个 文件 时 ， 服 务 端 会 及 时 更 新 它 在 内 存 中 对 你 的 代码 库 的 分 析 。 在 你 准备 运行 程序 的 时 候 ， 分 析 已 经 完成 了 。 客 户 端 仅仅 是 简单 地 
查询 服务 端 ， 并 且 几 乎 瞬时 展示 分 析 的 结果 。 这 个 “及 时 反馈 ”的 功能 很 容易 与 各 种 程序 编辑 器 和 1DE 合 并 。 


第 二 点 ，Hack 的 变量 类 型 标注 是 设计 成 渐进 式 的 。 你 可 以 按 自己 的 心愿 使 用 这 项 功能 。 类 型 标注 过 的 代码 可 以 和 没有 类 型 标注 过 Hack 代 码 或 者 PHP 代 码 无 颖 对 接 。 除 此 之 外 ， 你 如 果 不 标注 本 地 变量 
类 型 ， 类 型 检查 器 会 从 它 的 上 下 文中 推断 出 相关 的 类 型 。 


1.2 ”设置 类 型 检查 器 


在 正式 学 习 Hack 类 型 注解 的 语法 以 及 语义 之 前 ， 我 们 将 首先 学 习 如 何 设置 类 型 检查 器 。 


你 需要 做 的 第 一 件 事情 就 是 建立 一 个 .hhconfig 文 件 ， 这 个 文件 掌控 着 整个 项 目 范围 内 的 配置 项 目 ， 它 


来 标记 你 的 代码 库 的 顶级 目录 ， 使 得 类 型 检查 器 能 够 知晓 在 它 的 分 析 过 程 中 要 包含 哪些 文件 。 


目前 来 说 ， 我 们 还 不 需要 什么 配置 ，.hhconfig 文 件 还 是 个 空 文件 。 所 以 请 [导航 到 你 的 项 目的 顶级 目录 ， 然 后 输入 下 面 的 代码 : 


$ touch .hhconfig 
$ hh client 


执行 hh_client 命 令 将 首先 检测 是 否 存 在 hh_server 进 程 ， 如 果 没 有 这 个 进程 ， 客 户 端 会 主动 执行 一 个 。 所 以 你 不 必 自 己 去 执行 hh_server 进 程 ， 服 务 端 会 去 查找 .hhconfig 文 件 并 且 主 动 去 分 析 .hhconfig 
文件 同 级 及 子 目录 下 面 的 所 有 Hack 文 件 。 


一 个 标准 的 Hack 文 件 的 内 容 必须 以 <? hh 四 开头 ， 这 点 和 PHP 的 “开始 标记 ”语法 是 一 致 的 。 在 <? hh 标记 之 后 〈 可 能 会 有 辅助 的 模式 说 明 ， 请 参见 1.4.1 节 的 “类 型 检查 器 模式 ”的 内 容 ) ， 剩 下 的 就 
是 Hack 代 码 的 其 他 内 容 了 。 和 PHP 有 所 不 同 的 是 ， 结 束 符 ? > 在 Hack 语 言 中 是 不 生效 的 ， 所 以 不 能 在 Hack 语 言 中 使 用 PHP“ 模 板 化 语言 (templating-language) ”的 语法 了 。 


文件 的 扩展 名 无 关 紧要 ， 按 照 约 定 命名 为 .hh 文件 或 者 .php 文 件 都 是 可 以 的 。 


一 旦 类 型 检查 服务 端 被 启动 ， 如 果 在 你 的 项 目 中 没有 Hack 文 件 (也 就 是 说 ， 你 的 所 有 代码 都 包 庄 在 <? php 标 记 之 中 而 不 是 <? hh 标记 之 中 ) ， 运 行 hh_client 将 会 简单 地 输出 “No Errors! ”这 是 因 
为 类 型 检查 器 仅仅 查看 Hack 文 件 ， 它 对 PHP 文 件 不 会 做 任何 事情 。 


1.2.1 ”自动 加 载 一 切 


类 型 检查 器 做 出 的 一 个 关键 假设 就 是 ， 你 的 项 目 经 过 设置 后 ， 代 码 库 中 的 任何 类 、 函 数 或 者 常量 都 能 够 在 你 代码 库 的 其 他 地 方 使 用 。 不 会 尝试 去 分 析 任 何 include 或 者 require 语 句 ， 确 保 当前 文件 在 使 
时 已 经 加 载 了 其 他 文件 。 相 反 ， 它 认为 你 已 经 完成 了 “自动 加 载 ” 的 相关 设置 。 


这 就 简单 地 回避 了 两 个 问题 ， 一 是 困难 的 静态 分 析 的 问题 ， 另 一 个 是 现代 的 最 佳 实践 的 问题 。 “自动 加 载 一 切 ”的 是 被 Composer (流行 的 PHP 和 Hack 的 包 管理 器 ) 采取 的 方案 。 值 得 注意 的 是 ， 自 动 
加 载 并 不 是 强制 的 ， 你 可 以 在 代码 里 面 使 用 require 或 者 include 语 句 ， 关 于 这 一 点 ， 类 型 检查 器 并 不 会 产生 问题 。 但 是 我 们 强烈 建议 你 不 要 这 么 做 ， 因 为 类 型 检查 器 不 会 保护 你 免 受 require 或 者 include 语 句 
丢失 问题 的 困扰 。 


PHP 通 过 _autoload () 和 spl_autoload register () 提供 类 的 自动 加 载 功能 ，HHVM 也 支持 这 一 点 。HHVM3 提 供 了 新 的 附加 特性 ， 就 是 可 以 自动 加 载 PHP 或 者 Hack 的 函数 和 常量 ， 还 可 以 自动 加 载 
Hack 中 的 类 型 别名 (参见 3.2 节 的 内 容 ) 。 关 于 HHVM 所 特有 的 AP1， 可 以 查看 3.7 节 的 内 容 。 


1.2.2” 读 懂 报 错 消息 


类 型 检查 器 的 报错 消息 设计 得 详细 又 容易 理解 。 下 面 是 个 将 会 触发 错误 的 示例 代码 。 


<?hh 

function main() { 
$a = 10; 
$a[l] = 20; 


我 们 将 把 它 保存 成 为 一 个 名 为 test.hh 的 文件 ， 并 且 运 行 类 型 检查 器 : 


$ hh_client 
/home/oyamauchi/test.hh:4:3,6: an int does not allow array append (Typing[4006]) 
/home/oyamauchi/test.hh:3:8,9: You might want to check this out 


每 行 都 显示 了 有 错误 文件 的 全 路 径 消息 ， 紧 随 其 后 的 是 错误 代码 开始 和 结束 的 行 编号 与 列 编号 。 第 一 个 错误 消息 行 解释 了 现行 的 错误 消息 是 “一 个 整 型 不 允许 数组 进行 附加 ”， 然 后 给 出 一 个 能 够 唯一 
标识 错误 消息 的 数字 (参见 3.11 节 的 内 容 ， 具 体 查看 是 怎么 使 用 的 ) 。 行 号 和 列 号 指向 代码 $a[。 


代码 的 下 一 行内 容 是 缩 进 的 ， 表 了 明 这 不 是 一 个 单独 的 错误 ， 而 是 对 前 一 行 的 详细 说 明 。 它 解释 了 为 什么 类 型 检查 器 会 认为 9a 是 一 个 整 型 : 它 指向 了 已 经 赋值 给 “$a” 的 代码 “10”。 


四 在 命名 行 下 面 。 
加 一 个 Hack 文 件 是 允许 以 一 个 shebang 行 开始 的 ， 比 如 #!/ust/bin/hhvm, 但 是 <?hh 必 须 是 紧 接着 的 非 空 行 。 


1.3 ”类 型 标注 语法 


本 节 解 释 了 可 以 使 用 类 型 注解 语法 的 三 个 地 方 。 当 然 ， 我 们 还 没有 看 到 Hack 所 支持 的 全 部 类 型 ， 这 些 内 容 将 会 在 1.4 节 进行 讲述 。 现 在 ， 你 需要 知晓 的 就 是 int 和 string 是 有 效 的 类 型 标注 类 型 。 


可 以 使 用 类 型 标注 的 三 个 地 方 分 别 是 函数 的 返回 类 型 、 函 数 的 参数 和 属性 值 。 


1.3.1 ”函数 的 返回 类 型 


关于 函数 返回 类 型 的 语法 是 最 简单 的 ， 在 函数 参数 列表 结束 的 圆 括号 后 面 ， 添 加 一 个 冒号 和 一 个 类 型 名 称 。 你 可 以 在 函数 或 者 方法 中 这 样 使 用 ， 甚 至 那些 没有 具体 内 容 的 接口 和 抽象 类 的 方法 声明 中 也 
可 以 这 样 使 用 。 下 面 是 范例 : 


function returns an int(): int { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


function returns a string(): string { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


在 结束 的 圆 括号 和 冒号 中 间 的 空白 字符 是 允许 存在 的 。 如 果 函 数 签名 太 长 而 无 法 放 在 一 行 上 时 ， 通 常 可 以 在 结束 的 圆 括号 和 冒号 之 间 插 入 一 个 换行 符 。 


闭 包 也 可 以 拥有 返回 类 型 注解 : 


$add one = function ($x): int { return $x + 1; }; 
$agdd n = function ($x): int use ($n) { return $x + $n; }; 


这 个 语法 和 将 会 在 PHP 7 中 发 布 的 类 型 提示 (typehint) 语法 兼容 ， 除 了 使 用 捕获 变量 列表 的 闭 包 的 情况 之 外 。 在 PHP 7 中 ， 返 回 类 型 提示 在 捕获 变量 列表 后 面 ， 但 是 在 Hack 中 ， 它 出 现在 参数 列表 后 
面 。 


1.3.2 “函数 的 参数 


给 函数 的 参数 做 类 型 标注 的 语法 和 PHP 中 使 用 类 型 提示 参数 的 语法 一 致 ， 都 是 把 类 型 名 称 放 在 参数 名 之 前 。 


function f(int $start, string Sthing) { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


参数 的 默认 值 也 一 如 既往 地 被 支持 ， 但 前 提 是 默认 值 要 符合 类 型 标注 。 在 PHP 中 这 里 对 于 类 型 提示 参数 特别 允许 设置 默认 值 为 null。 所 以 下 方 的 内 容 是 有 效 的 : 


function f(SomeClass Sobj = null) { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 


但 是 这 种 写法 在 Hack 中 是 无 效 的 ， 因 为 它 混淆 了 可 选 参数 的 概念 和 人 允许 一 个 占 位 值 的 必 填 参数 的 概念 。 在 Hack 中 ， 可 以 通过 把 一 个 参数 类 型 标记 为 nullable 的 方法 来 表述 后 者 (参见 1.4 节 ) 。 


parameter (参数 ) 和 argument (参数 ) 


这 两 个 词 在 程序 员 的 日 常 交 流 中 经 常 交替 使 用 。 但 是 事实 上 ， 它 们 并 不 是 同一 个 东西 ， 这 两 者 的 区 别 是 就 像 变量 variable 和 值 value 的 区 别 一 样 ，parameter 是 变量 ， 而 atgument 是 值 ， 即 一 个 函数 被 调用 的 时 
候 ， 传 递 给 变量 的 具体 值 。 思 考 下 面 的 代码 : 


function adqd_one (Sx) { 
return $x + 1} 


} 
echo add one(10); 


$x 是 函数 add_one 的 一 个 变量 ,而 10 就 是 一 个 赋 给 变量 $x 的 值 。 
所 以 当 我 们 说 一 个 函数 拥有 (has) parametet 的 时 候 ， 正 确 的 说 法 应 该 是 它 接 受 了 argument， 因 为 当 你 调用 这 个 函数 的 时 候 ， 传 递 了 argument 给 它 。 


可 变 参 数 函 数 就 是 参数 值 数量 不 定 的 函数 。 在 PHP 中 ， 所 有 的 函数 都 是 隐 式 的 、 参 数 可 变 的 ， 传 递 给 一 个 函数 超过 它 规定 参数 之 外 多 余 的 参数 值 并 不 会 触发 错误 ， 并 且 任 何 函数 都 可 以 通过 内 置 的 
func get args () 、func_get arg () 和 func_num_args () 获得 你 传递 给 它 的 所 有 参数 值 。 


与 此 相反 的 是 ， 在 Hack 中 传递 过 量 的 参数 给 一 个 函数 将 会 触发 一 个 错误 ， 除 非 这 个 函数 显 式 地 声明 为 一 个 可 变 参数 函数 。Hack 中 创建 一 个 可 变 参数 函数 的 语法 是 ， 放 置 一 个 
http:/Mwww.hzcourse.coryresource/readBook?path=/openresources/teach_ebook/uncompressed/16125/OEBPS/Text/… 到 函数 签名 之 中 。 在 这 样 的 函数 之 中 ， 就 像 在 PHP 中 一 样 ， 可 以 通过 
func_get args () 、func get arg () 以 及 func_num_args () 获得 这 些 参数 值 。 


function log error(string $format, http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/OEBPSVText/...) { 
$varargs = func get args(); 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


可 变 参数 允许 是 任意 类 型 的 ，log_error () 函数 的 第 一 个 参数 值 必 须 是 一 个 字符 串 ， 但 是 随后 的 参数 值 可 以 是 任何 Hack 的 类 型 检查 器 可 以 接受 的 类 型 。 


1.3.3 属性 


在 属性 声明 之 中 (不 管 是 静态 的 还 是 非 静态 的 ) ， 类 型 标注 总 是 直接 出 现在 属性 名 之 前 : 


class C { 
public static int $logging level = 2; 
private string $name; 


} 


初始 变量 值 是 被 支持 的 (就 像 范例 中 的 2 被 赋值 给 $logging_level 一 样 ) ， 并 且 初始 化 的 值 必须 和 类 型 标注 相 一 致 。 


区 属性 的 初始 化 事实 上 还 有 很 多 规则 ， 为 了 避免 你 的 代码 会 访问 一 个 并 没有 被 初始 化 的 属性 ， 请 查看 1.5.3 节 的 内 容 。 


1.4 ”Hack 的 类 型 系统 


Hack 提 供 了 一 系列 强 有 力 的 方法 来 描述 类 型 ， 在 PHP 最 基本 的 布尔 型 、 整 型 、 字 符 串 型 、 数 组 等 类 型 系统 的 基础 上 ， 添 加 了 很 多 新 的 方式 来 结合 它们 ， 并 且 使 之 更 富有 表现 力 。 
这 里 有 和 PHP 一 样 的 原始 类 型 : bool、int、float、string、array 和 resource， 这 些 都 是 合法 有 效 的 Hack 类 型 标注 。 


在 PHP 中 ， 有 为 这 些 类 型 专门 附加 的 名 字 ， 比 如 boolean、integer、real 和 double 类 型 ， 但 是 这 些 在 Hack 中 都 不 是 合法 有 效 的 ， 上 段 提 及 的 6 种 类 型 是 Hack 类 型 系统 中 可 以 被 接受 的 原始 类 型 。 


作为 原始 类 型 的 有 效 补 充 ， 这 里 还 有 其 他 两 种 类 型 : num， 可 以 是 整 型 或 者 浮 点 数 类 型 ;arraykey， 可 以 是 整 型 ， 也 可 以 是 字符 串 类 型 。 


对 象 类 型 


任何 类 或 者 接口 的 名 字 (内 置 或 者 非 内 置 的 ) 都 能 够 在 类 型 标注 中 使 用 。 


枚 举 类 型 


枚 举 类 型 在 第 3 章 中 会 更 加 全 面 地 阐述 ， 这 里 我 们 只 需要 知道 枚 举 类 型 就 是 一 组 常量 值 的 名 字 。 枚 举 类 型 的 名 字 能 够 用 做 类 型 标注 。 对 应 的 类 型 标注 的 合法 值 就 是 这 个 枚 举 里 面 的 成 员 。 


元 组 类 型 


元 组 是 一 个 把 固定 数目 的 不 同类 型 的 值 进行 打包 的 办 法 ， 元 组 类 型 最 通常 的 用 途 就 是 从 函数 中 返回 多 个 值 。 


元 组 类 型 标准 的 语法 非常 简单 ， 就 是 用 括号 括 住 ， 用 逗号 分 隔 的 类 型 列表 (可 能 在 列表 中 出 现任 何其 他 类 型 ， 但 是 void 类 型 不 会 出 现 ) 。 创 建 一 个 元 组 类 型 的 语法 和 创建 数组 类 型 的 array () 语法 一 
样 ， 区 别 在 于 关键 词 “array” 被 “tuple” 代替 ， 并 且 不 能 有 键 名 key。 
例如 ， 函 数 将 会 返回 一 个 包含 整数 值 和 浮 点 数 的 元 组 类 型 。 
function find max and index(array<float> Snums) : (int, float) { 
Smax = -INF; 
Smax index = -1; 


foreach (Snums as $index => Snum) { 
if ($num > Smax) { 
Smax = $num; 
Smax index = $index; 
} 
} 


return tuple ($max index, $max); 


元 组 类 型 的 表现 更 像 一 个 受 限 版 的 数组 类 型 ， 你 不 能 修改 元 组 类 型 的 key 集 合 ， 也 就 是 说 ， 你 不 能 添加 或 者 移 除 对 象 。 你 能 够 修改 一 个 元 组 中 的 值 ， 但 是 你 不 能 修改 它们 的 类 型 。 你 能 
语法 读 出 元 组 内 的 值 ， 但 是 更 通常 的 做 法 是 通过 列表 分 配 把 元 组 类 型 解 包 ， 而 不 是 读 取 某 个 单独 的 元 素 。 


从 底层 上 讲 ， 元 组 类 型 确实 就 是 数组 ， 如 果 你 把 一 个 元 组 类 型 传递 给 函数 js_array () ， 这 个 函数 将 会 返回 true。 


混合 型 (mixed) 


mixed 意 味 着 包含 hull 在 内 的 Hack 编 程 语言 里 面 所 允许 的 任何 值 。 


void 


够 通过 数组 编号 的 


void 只 在 函数 返回 类 型 中 有 效 ， 它 意味 着 这 个 函数 什么 也 没有 返回 。 (在 PHP 中 ， 如 果 一 个 函数 什么 也 不 返回 的 话 ， 那 么 事实 上 返回 了 一 个 null 的 值 。 但 是 在 Hack 中 ， 函 数 返 回 值 返 回 viod 的 话 会 引发 


一 个 错误 。) 
void 包 含 在 mixed 类 型 中 ， 也 就 是 说 ， 如 果 一 个 函数 的 返回 类 型 是 mixed， 那 么 它 什 么 也 不 返回 是 合法 的 。 


this 


this 只 在 方法 返回 类 型 中 有 效 ， 对 于 一 个 空 函 数 来 党，this 并 不 是 一 个 有 效 的 返回 类 型 。 这 表明 这 个 方法 返回 了 一 个 类 的 对 象 ， 该 对 象 的 类 与 这 个 方法 调用 时 所 在 对 象 的 类 相同 。 


这 种 类 型 标注 的 目的 就 是 允许 在 有 子 类 的 类 上 进行 链 式 方法 调用 ， 链 式 方法 调用 是 个 非常 有 用 的 技巧 ， 它 们 看 起 来 是 这 样 的 : 


$random = $rng->setSeed (1234) ->generate () 7 


为 了 实现 写 链 式 调用 ， 题目 中 的 类 必须 从 那些 没有 钦 辑 返回 值 的 方法 返回 $this， 就 像 这 样 : 


class RNG { 
private int $seed = 0; 


public function setSeed(int $seed): RNG { 
$this->seed = $seed; 
return S$this; 


} 


// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


在 这 个 例子 中 ， 如 果 类 RNG 没 有 子 类 ， 你 可 以 使 用 RNG 作 为 setSeed () 方法 的 返回 类 型 标注 ， 这 不 会 有 任何 问题 ， 但 是 当 RNG 有 子 类 的 时 候 ， 就 会 出 问题 了 。 


在 接 下 来 的 例子 中 ， 类 型 检查 器 将 会 报告 一 个 错误 。 因 为 方法 setSeed () 的 返回 类 型 是 RNG， 它 认为 调用 $rng->setSeed (1234) 将 会 返回 一 个 RNG 类 型 ， 并 且 在 RNG 对 象 上 调 
generateSpecial () 方法 是 非法 的 ， 因 为 这 个 方法 仅仅 定义 在 子 类 中 。 更 多 $rng 变 量 特别 指明 的 类 型 (类 型 检查 器 知道 这 个 类 型 是 SpecialRNG) 已 经 丢失 了 。 


class SpecialRNG extends RNG { 
public function generateSpecial(): int { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


} 


function main(): void { 

$rng = new SpecialRNG(); 

$special = $rng->setSeed (1234) ->generateSpecial (); 
} 


返回 类 型 标注 thisI5 妙 地 解决 了 这 个 问题 : 


Class RNG { 
private int $seed = 0; 


public function setSeed(int $seed): this { 
$this->seed = $seed; 
return S$this; 


} 


// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


现在 ， 当 类 型 检查 器 计算 $rng->setSeed (1234) 调用 的 返回 类 型 的 时 候 ，this 变 量 标注 将 告诉 它 保持 箭头 左边 表达 式 的 类 型 ， 这 就 是 说 ， 关 于 generateSpecial () 的 链 式 调用 将 是 合法 的 。 


静态 方法 也 能 够 使 用 返回 类 型 this， 在 这 种 情况 下 ， 它 表明 它们 返回 了 一 个 对 象 ， 这 个 对 象 的 类 就 是 这 个 方法 所 在 的 类 ， 就 是 说 ， 从 函数 get_called_class () 返回 的 类 的 名 字 。 满 足 this 类 型 标注 的 办 
法 就 是 返回 new static () : 


class ParentClass 
// 这 全 各 各 逢 2 奖 芥 栓 在 加 "new static() ' 是 合法 的 


final protected function tae {} 


public static function newInstance(): this { 
return new static(); 
} 
. 


class ChildClass extends ParentClass { 


} 


function main(): void { 
ParentClass: :newInstance (); // 返 个 ParentClass 的 实例 
ChilgClass: :newInstance (); // 返回 一 个 childclass 的 实例 
} 


类 型 别名 


在 3.2 节 中 将 详细 阐述 ， 类 型 


别名 是 对 已 经 存在 的 类 型 重新 命名 的 好 办 法 ， 你 可 以 使 用 新 名 字 作 为 类 型 标注 。 


Shape 


Shape 类 型 是 个 非常 特别 的 类 型 别名 ， 将 在 3.3 节 中 详细 描述 ， 并 且 它 们 的 名 字 也 能 够 作为 类 型 标注 使 用 。 


Nullable 类 型 


除 void 和 mixed 之 外 的 所 有 类 型 都 能 够 通过 问号 前 缀 符号 标注 为 可 为 空 的 。 对 于 ? int 的 类 型 标注 来 说 ， 它 能 够 是 整 型 也 可 以 是 null 类 型 。mixed 类 型 不 能 够 标注 为 nullable 的 原因 就 是 它 已 经 包含 了 null 
类 型 。 


Callable 类 型 


虽然 PHP 人 允许 callable 作 为 一 个 参数 的 类 型 提示 ， 但 是 Hack 并 不 允许 。 相 反 ，Hack 提 供 了 更 为 强大 的 语法 ， 人 允许 你 明确 指出 不 仅仅 一 个 值 是 可 调用 的 ， 还 包括 它 作 为 参数 值 时 是 什么 类 型 的 ， 以 及 它 返 
回 的 是 什么 类 型 。 


这 个 类 型 的 语法 是 一 个 关键 词 function， 后 面 是 括号 括 住 的 参数 类 型 列表 ， 再 后 面 是 冒号 和 返回 类 型 ， 上 述 这 些 再 包 在 一 个 括号 内 。 这 有 些 像 给 函数 做 变量 标注 的 语法 ; 从 根本 上 来 说 ， 这 就 是 一 个 没 
有 函数 名 和 参数 名 的 函数 签名 。 在 下 面 的 例子 中 ，$callback 就 是 这 样 一 个 函数 ， 它 的 参数 是 一 个 整 型 和 一 个 字符 串 类 型 ， 返 回 字符 串 类 型 : 


回 


function do some work (array $items, 
二 (function (int，string) : string) $callback): array { 
foreach ($items as S$index => S$value) { 
$string result = $callback ($index, $value); 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 
} 


满足 callable 类 型 标注 的 callable 值 有 四 种 情况 : 闭 包 、 函 数 、 实 例 方法 和 静态 方法 。 让 我 们 通过 下 面 的 例子 加 深 一 下 理解 : 


“下面 是 一 个 简单 的 闭 包 的 例子 : 


function do_some work((function (int) : void) $callback): void { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 


function main(): void { 
do_some _ work (function (int $x): void { /* http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... */ }); 


} 


“ 如 果 要 使 用 一 个 已 经 命名 的 函数 作为 callable 的 值 ， 你 需要 通过 一 个 特别 的 函数 fun () 来 传递 函数 名 ， 例 丸 


function do_some work((function (int): void) $callback): void { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 


function fl(int $x): void { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 


function main(): void { 
do_some work (fun('f"')); 


} 


fun () 函数 的 参数 必须 是 一 个 单 引号 的 字符 串 字面 量 ， 类 型 检查 器 会 自动 查找 函数 名 ， 并 且 检 测 它 的 参数 类 型 和 返回 类 型 ， 然 后 把 fun () 当成 它 返 


回 


了 一 个 正确 类 型 的 callable 的 值 。 


“ 当 使 用 实例 方法 作为 callable 的 值 时 ， 你 必须 通过 特殊 的 函数 inst_meth () 来 传递 对 象 及 方法 名 ， 这 点 和 fun () 函数 很 像 ， 类 型 检查 器 将 会 查找 对 应 名 称 的 方法 ， 并 且 将 inst_meth () 当成 它 返回 了 正 
确 类 型 的 callable 值 一 样 。 再 次 说 明 一 下 ， 方 法 名 必须 是 单 引 号 的 字符 串 字 面 量 : 


function do_some work ((function (int) : void) S$callback) : void { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/.. 
} 


Class C { 
public function do work(int $x) void { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 
} 


function main() : 
$c = new C(); 
do_some work(inst meth($c, 'do work')); 


} 


void {} 


“ 使 用 静态 方法 也 非常 相似 : 把 类 名 和 方法 名 通过 函数 class_meth () 传递 即 可 。 方 法 名 必须 是 个 单 引 号 的 字符 串 字面 量 。 类 名 可 以 是 个 单 引 号 的 字符 串 字面 量 ， 或 者 是 Hack 中 特有 的 : : class 构 造 附加 
一 个 非 单 引号 的 类 名 后 面 。 


function do_ some work ((function (int) : void) : $callback): void { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 


class CI{ 
public static function Prognosticate (int $x): void { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 
} 


function main(): void { 
do_some work(class meth(C::class, 'prognosticate')); 
// 等 价 于 : 


do_some work(class meth('C', 'prognosticate')); 


} 


在 运行 环境 中 ，ClassName: : class 是 和 'ClassName' 等 价 的 。 


这 里 还 有 另外 一 种 办 法 来 创建 一 个 调用 实例 方法 的 callable 值 ， 这 就 是 meth_call () 函数 。 它 将 通过 调 
方法 必须 没有 任何 参数 ， 这 个 局 限 性 在 未 来 的 版 本 中 将 被 解除 。 


你 传递 给 它 的 一 个 实例 对 象 上 的 方法 ， 来 创建 一 个 可 调用 的 值 。 这 里 有 个 局 限 性 ， 就 是 ， 这 个 


class C { 
function speak(): void { 
echo "hi!l"; 
} 
} 


function main(): void { 
$caller = meth caller(C::class, 'speak'); 
$obj = new C()7 
$caller ($obj); ”// 等 价 于 调用 $obj->speak (); 
} 


与 能 够 打包 一 个 特定 对 象 和 调用 它 的 方法 的 函数 inst_meth () 相 比 ，meth_caller () 函数 与 array map () 和 array filter () 这 样 的 工具 函数 一 起 使 用 特别 有 用 。 例 如 : 


class User { 
Public function getName () : string { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


} 


function all names (array<User> $users): string { 
Snames = array map ($users, meth caller(User::class, 'getName')); 
return implode(', ', $names); 


} 


当然 ， 有 一 种 值 在 PHP 中 是 可 调用 的 ， 但 是 在 Hack 的 类 型 检查 器 中 却 不 能 识别 : 拥有 一 个 _invoke () 方法 的 对 象 。 这 个 问题 未 来 将 会 被 改进 。 


泛 型 


也 被 称 作 参 数 化 类 型 ， 泛 型 允许 一 段 代 码 在 同一 方式 下 使 用 多 种 不 同 的 类 型 ， 并 且 保 证 仍然 可 验证 为 类 型 安全 的 。 最 简单 的 例子 是 取代 简单 指定 一 个 值 是 一 个 数组 ， 你 可 以 通过 泛 型 指定 一 个 字符 串 组 
成 的 数组 ， 或 者 由 一 个 Person 类 的 对 象 组 成 的 数组 等 。 


泛 型 是 非常 强大 的 工具 ， 这 里 仅 做 简单 了 解 ， 我 们 将 在 第 2 章 做 全 面 的 阐述 。 


对 于 本 章 而 言 ， 已 经 足够 了 解 泛 型 数组 的 语法 了 。 它 通常 由 关键 词 array 开 头 ， 然 后 紧 随 着 的 是 一 个 或 者 两 个 由 尖 括 号 包 住 的 类 型 名 称 。 如 果 在 尖 括 号 内 只 有 一 个 值 ， 那 么 这 个 类 型 就 是 数组 中 value 的 
类 型 ， 并 且 数 据 的 key 被 认为 是 int 类 型 。 如 果 尖 括号 内 有 两 个 类 型 ， 那 么 第 一 个 就 是 key 的 类 型 ， 第 二 个 就 是 value 的 类 型 。 举 例 说 明 如 下 : array<bool> 意 味 着 整 型 数组 的 key 映 射 到 布尔 型 的 值 ， 而 
array<string，int> 意 味 着 字符 串 类 型 的 key 映 射 到 整 型 。 尖 括号 里 面 的 类 型 被 称 为 类 型 实 参 。 


需要 重点 说 明 的 是 ， 一 个 值 如 果 在 PHP 中 不 能 被 创建 ， 那 么 在 Hack 中 你 也 不 能 创建 这 个 值 。PHP 和 Hack 的 基础 元 素 都 是 一 致 的 ，Hack 的 类 型 系统 仅仅 为 更 有 意思 的 组 合 和 可 能 值 的 子 集 提 供 了 新 的 表 


更 具体 地 说 ， 请 思考 下 面 的 代码 : 


function main(): void { 
£(10 10)? 
} 


function f(mixed $m, int $i): void 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


在 函数 f () 的 函数 体内 ， 我 们 说 $m 是 一 个 mixed 类 型 的 变量 ， 而 $ 是 一 个 int 类 型 的 变量 ， 虽 然 它们 实际 上 存储 的 是 同样 的 东西 。 


或 者 想 想 下 面 的 代码 : 


function main(): void { 


$callable = function (string $s): ?int { /* http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... */ }; 
} 


里 


虽然 我 们 说 变量 $callable 是 (function (string) : ? int) 类 型 ， 但 是 在 此 情况 下 ， 它 和 其 他 闭 包 一 样 ， 仍 然 是 个 对 象 。 它 并 不 是 一 个 仅 在 Hack 中 存在 的 神奇 函数 指针 ， 或 者 : 


他 类 似 的 概念 。 
一 般 来 说 ， 如 果 我 们 表述 某 个 变量 是 某 个 类 型 的 话 ， 这 个 表述 是 类 型 检查 器 知晓 的 ， 但 并 不 是 运行 环境 所 知晓 的 。 


1.4.1 ”类 型 检查 器 模式 


Hack 的 类 型 检查 器 有 三 种 模式 : 严格 (strict) 、 局 部 (partial) 和 耦合 (decl) 。 这 些 模式 都 基于 一 个 个 单独 的 文件 ， 不 同 模式 下 的 单独 文件 可 以 无 颖 地 进行 对 接 。 每 个 文件 可 以 单独 声明 它 的 类 型 检 
查 模式 ， 语 法 就 是 在 文件 的 第 一 行使 用 一 个 双 和 斜 线 的 注释 。 如 下 面 的 代码 所 示 : 


<?hh // strict 


如 果 文 件 的 第 一 行 没有 上 述 类 似 的 注释 信息 (比如 第 一 行 就 是 一 个 <? hh) ， 将 默认 使 用 局 部 模式 。 


这 三 种 模式 间 有 很 多 的 不 同 之 处 ， 通 过 对 这 些 差异 点 的 学 习 ， 我 们 可 以 了 解 类 型 检查 器 的 很 多 特性 。 下 面 是 对 每 种 模式 的 具体 说 明 。 


严格 模式 : <? hh//strict 


严格 模式 最 重要 的 特性 就 是 ， 所 有 命名 的 函数 (以 及 方法 ) 都 必须 有 返回 类 型 和 参数 类 型 标注 ， 所 有 的 属性 也 必须 进行 类 型 标注 。 换 名 话说， 任何 可 能 出 现 类 型 标注 的 地 方 都 必须 进行 标注 。 但 是 有 如 
下 例外 : 


“ 闭 包 不 需要 对 参数 类 型 和 返回 类 型 进行 标注 。 
: 构造 函数 和 析 构 函数 不 需要 返回 类 型 标注 ， 非 要 让 它们 返回 些 什 么 也 说 不 通 。 


在 严格 模式 下 有 三 条 主要 的 限制 : 


使 用 任何 在 Hack 文 件 中 没有 定义 过 的 命名 实体 帽 都 会 引发 错误 。 这 就 是 说 ， 严 格 模式 下 的 Hack 代 码 无 法 调用 PHP 代 码 。 但 是 严格 模式 下 面 的 Hack 代 码 可 以 调用 局 部 模式 或 者 辜 合 模式 的 Hack 代 码 。 
“ 顶层 文件 中 的 大 多 数 代码 将 会 导致 错误 。require 系 列 语句 是 允许 的 中， 因为 它们 用 于 定义 命名 实体 症 。 
“使 用 引用 赋值 (比如 $a=&$b) ， 或 者 定义 了 “通过 引用 返回 值 或 者 引用 接收 参数 ”的 函数 或 方法 ， 都 会 引发 错误 。 


还 有 一 些 其 他 更 小 的 不 同 点 ， 我 们 将 会 进行 补充 。 


为 了 充分 利用 类 型 检查 器 的 便利 性 ， 我 们 应 该 致力 于 尽 可 能 地 写 严格 模式 的 Hack 代 码 。 严 格 模式 的 Hack 是 个 健全 的 系统 ， 这 就 意味 着 ， 如 果 你 的 代码 100% 是 在 严格 模式 ， 那 么 你 在 代码 运行 时 绝 无 可 
能 引发 类 型 错误 的 。 这 是 一 个 非常 强大 的 保证 ， 你 越 接近 这 点 越 好 。 


局 部 模式 : <? hh 


局 部 模式 放宽 了 严格 模式 的 种 种 限制 ， 它 可 以 做 它 能 够 做 的 任何 类 型 检查 ， 但 是 它 不 要 求 代码 里 面 必须 写 所 有 的 类 型 标注 。 此 外 ， 


:如果 你 正在 使 用 函数 或 者 类 ， 类 型 检查 器 不 能 在 Hack 文 件 中 发 现 的 话 ， 这 并 不 会 引发 错误 。 类 型 检查 器 会 宽大 地 认为 这 些 丢失 的 实体 都 定义 在 一 个 PHP 文 件 中 ， 具 体 可 以 查看 1.4.3 节 的 内 容 。 


“ 顶层 代码 是 允许 的 ， 但 是 不 会 检查 类 型 。 所 以 为 了 最 小 化 不 执行 类 型 检查 的 代码 数量 ， 在 理想 的 情况 下 ， 你 应 该 把 所 有 的 顶层 代码 包装 进 某 个 函数 ， 然 后 在 你 唯一 的 顶层 代码 语句 中 调用 上 述 函 数 。 
下 面 是 个 相关 的 例子 ， 最 好 不 要 这 样 做 : 


<?hh 

set up autoloading(); do logging(); 
$c = find controller(); $c->go(); 
而 改 为 这 样 做 : 

<?hh 


function main() { 
set up autoloading (); 
do_logging(); 


$c = find controller(); 
$c->go(); 
main(); 


更 好 的 做 法 是 把 main 函 数 的 定义 放 到 一 个 严格 模式 的 文件 中 。 


“ 引用 是 允许 的 ， 但 是 类 型 检查 器 本 质 上 假装 引用 的 相关 代码 不 存在 ， 并 不 会 试图 去 规范 它们 的 行为 。 在 本 例 中 ， 代 码 的 最 后 一 行 后 面 类 型 检查 器 仍然 会 认为 $a 是 个 整 型 ， 尽 管事 实 上 它 是 一 个 字符 串 


类 型 。 
$a = 10; 
Sb = &$a; 
$b = 'not an int'; 


简单 来 说 ， 可 以 在 局 部 模式 下 使 用 引 


， 但 是 这 破坏 了 类 型 安全 ， 所 以 你 应 该 尽量 避免 使 用 它们 。 


甚至 对 于 一 个 从 头 开始 建立 的 新 Hack 项 目 来 说 ， 这 里 仍然 有 局 部 模式 的 文件 需求 。 在 任何 的 脚本 或 者 Web 应 用 中 ， 总 是 需要 有 一 定数 量 的 顶层 代码 的 存在 ， 它 们 将 作为 入 口 点 代码 存在 。 所 以 你 将 至 少 
需要 一 个 局 部 模式 的 Hack 文 件 。 你 需要 使 用 局 部 模式 来 获得 超级 全 局 变量 ， 比 如 $_GET、$_POST 和 $argv， 我 们 将 在 1.5.1 节 对 此 展开 更 详细 的 六 述 。 


耦合 模式 : <? hh//decl 


在 耦合 模式 中 ， 代 码 是 不 会 被 检查 类 型 的 。 类 型 检查 器 做 的 所 有 事情 就 是 读 取 和 检索 所 有 的 函数 签名 以 及 定义 在 文件 中 的 类 。 (在 耦合 模式 下 仍然 会 触发 错误 ， 比 如 无 效 的 类 型 标注 语法 。) 


耦合 模式 存在 的 目的 在 于 ， 当 迁移 一 个 已 经 存在 的 PHP 代 码 库 到 Hack 代 码 时 ， 提 供 一 个 过 渡 的 功能 。 它 为 PHP 和 其 他 Hack 代 码 模式 提供 了 过 渡 的 垫 脚 石 。 转 化 一 个 PHP 文 件 到 耦合 模式 的 Hack 文 件 是 
非常 容易 的 ， 并 且 相 对 于 保留 为 PHP 文 件 而 言 ， 也 具有 显著 的 益处 。 首 先 ， 关 于 调用 PHP 代 码 的 类 型 检查 非常 宽松 。 (可 以 参见 1.4.3 节 ) ， 但 是 如 果 调用 耦合 模式 的 Hack 代 码 将 会 更 加 严格 地 进行 类 型 检 
查 。 其 次 ， 严 格 模式 的 Hack 代 码 是 根本 无 法 调用 PHP 代 码 的 ， 但 是 它 可 以 调用 耦合 模式 的 Hack 代 码 。 


如 果 你 正在 编写 一 个 全 新 的 、100% 纯 正 的 Hack 代 码 库 ， 那 么 你 不 应 该 使 用 耦合 模式 。 


1.4.2 ”没有 标注 的 代码 


这 里 有 一 种 我 在 早期 的 列表 中 没有 提 及 的 类 型 ， 即 没有 进行 类 型 标注 的 类 型 。 举 例 来 阅 ， 就 像 下 面 函数 体内 变量 $x 的 类 型 。 


function f($x) { 


在 代码 中 ， 你 并 没有 书写 任何 类 型 名 称 在 变量 $x 前 面 。 那 么 在 Hack 的 体系 里 面 ， 它 指 代 的 类 型 为 “任何 ”。 


类 型 检查 器 会 对 这 种 类 型 进行 特殊 处 理 ， 它 永远 不 会 卷 入 类 型 错误 中 ， 每 个 在 Hack 中 可 以 存在 的 值 都 会 符合 这 种 类 型 “标注 ”， 所 以 你 可 以 传递 任何 值 到 上 例 的 函数 f () 中 ， 而 不 必 担心 会 引发 类 型 
错误 。 换 个 角度 来 说 ， 这 种 类 型 的 值 符合 每 一 种 可 能 的 类 型 标注 ， 所 以 在 f () 函数 内 ， 你 可 以 拿 $x 做 任何 事情 ， 而 不 会 引发 类 型 错误 。 


这 听 起 来 和 mixed 类 型 很 相似 ， 但 是 这 里 有 个 非常 


个 期 待 int 类 型 的 函数 中 ， 你 必须 确保 它 是 个 整 型 ( 详 见 1.7.2 节 的 内 容 ) ， 或 者 强制 转化 它 。 


“任何 ”类 型 的 值 在 所 有 Hack 模 式 中 都 以 一 样 的 方式 工作 。 在 严格 模式 下 ， 


的 不 同 点 。 每 个 可 能 的 值 都 满足 mixed， 但 是 一 个 mixed 类 型 的 值 并 不 满足 每 个 可 能 的 类 型 标注 。 举 例 来 说 ， 如 果 你 传递 一 个 mixed 类 型 的 值 到 一 


你 不 能 书写 没有 标注 的 代码 ， 但 是 你 可 以 调 


在 “任何 可 以 标注 的 都 必须 标注 ”的 严格 模式 下 ， 严 格 模式 的 代码 可 能 使 


这 种 特殊 类 型 的 值 ， 但 是 绝对 不 允许 产生 它 。 


1.4.3 ”调用 PHP 代 码 


如 果 你 使 用 了 一 个 类 型 检查 器 无 法 在 任何 Hack 文 件 中 找到 的 命名 实体 ， 在 
的 行为 ， 但 是 真正 的 目的 在 于 Hack 代 码 从 PHP 迁 移 的 易 


何 分 析 ， 甚 至 都 不 会 去 分 析 你 的 PHP 文 件 里 面 定义 了 什么 函数 ， 这 些 都 是 需要 你 


在 


在 .hhconfig 文 件 中 添加 一 行 代码 “assume_php=false” 来 关闭 它 。 然 后 通过 命 


如 果 你 准备 迁移 一 个 大 的 PHP 代 码 库 到 Hack， 保 持 assume_php 选 项 开 
选择 ， 可 以 更 好 地 享受 严格 模式 带 来 的 好 处 。 当 然 了 ， 如 果 你 刚刚 开始 一 个 全 新 | 


局 部 模式 下 ， 对 于 上 述 情况 你 还 可 以 通过 配置 项 主动 触发 一 个 错误 。 这 个 选 


启 是 个 非常 好 的 注意 。 在 后 续 的 阶段 中 ， 随 着 代码 库 里 
的 代码 编写 工作 ， 最 好 在 最 开始 的 时 候 关 闭 这 个 选项 (设置 assume_php=false) 。 


自己 负责 的 。 


先 项 称 为 “assume_php” 


被 定义 在 | 


(就 是 “假设 丢失 的 实体 都 定义 在 PHP 生 
令 行 “hh_client restart” 重 启 类 型 检查 器 的 服务 端 。 


H 


的 Hack 项 


对 于 未 知 的 函数 或 者 类 的 使 


， 类 型 检查 器 设 定 了 最 大 的 宽容 性 假设 : 
* 对 未 知 疯 数 的 调用 ， 类 型 检查 时 认为 它 能 够 接纳 任何 数量 、 任 何 类 型 的 参 


“未知 的 常量 定义 被 认为 是 特殊 的 “任何 ”类 型 


就 像 它们 在 调用 一 个 没 


数值 ， 并 且 没 有 返回 类 型 标注 。 


有 任何 返回 类 型 标注 的 函数 结果 。 


局 部 或 者 耦合 模式 下 没有 类 型 标注 的 代码 。 


局 部 和 耦合 模式 下 并 不 会 引发 错误 (在 严格 模式 下 ， 这 将 会 触发 一 个 “unbound error”) 。 这 看 起 来 似乎 是 个 很 奇怪 的 宽松 
性 。 这 人 允许 Hack 文 件 中 的 代码 使 用 PHP 文 件 中 的 代码 : 调用 函数 、 使 用 常量 ， 甚 至 实例 化 和 


扩展 类 。 记 住 ， 类 型 检查 器 不 会 对 你 的 PHP 文 件 做 任 


人 


个 选项 默认 是 开启 的 。 你 可 以 通过 


有 E 面 ”的 意思 ) ， 这 


更 多 的 PHP 文 件 转变 为 Hack 文 件 ， 那 么 关闭 assume_php 选 项 是 更 好 的 


“ 实例 化 一 个 未 知 类 型 的 类 ， 得 到 的 结果 值 是 个 对 象 。 调 用 这 个 对 象 上 面 的 任何 方法 都 是 合法 的 ， 类 型 检查 上 就 像 调用 一 个 未 知 的 函数 。 任 何 对 这 个 对 象 的 属性 访问 也 是 合法 的 ， 并 且 返 回 的 值 将 具有 


特殊 的 “任何 ”类 型 。 


: 一 个 Hack 类 如 果 具 有 任何 未 知 的 祖先 类 ， 或 者 使 用 了 任何 未 知 的 特性 ， 或 者 其 任何 祖先 类 有 未 知 的 特性 ， 这 都 和 一 个 未 知 的 类 差不多 。 未 知 的 特性 或 者 类 会 大 大 削弱 整个 实体 结构 中 的 类 型 检查 器 。 


调用 上 述 类 中 的 任何 方法 或 者 访问 任何 未 知 属性 都 是 合法 的 。 


然而 ， 对 于 定义 在 Hack 文 件 中 的 方法 调 


或 者 


属性 访问 ， 如 果 类 型 检查 器 能 够 解决 的 话 ， 即 使 在 耦合 模式 下 ， 它 也 会 对 其 进行 适当 的 类 型 检查 。 例 如 : 


class C extends SomeClassNotDefinedInHack { 
public int $known property; 


public function known method(string $s) { 


// http://wuw.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


} 

function main(): void { 

$c = new C(); 
$c->unknown method(); // 
$c->known method(12); // 


没有 错误 

错误 : int 类 型 并 不 兼容 string 类 型 

// 没有 错误 ， 

// ”错误 : 不 能 在 一 个 int 类 型 上 调用 方法 


$c->unknown_ property->func (); 
$c->known_property->func (); 
} 


目 一 个 命名 的 实体 可 能 是 一 个 函数 、 类 、 接 口 、 
PP] require、include、require_once 和 include_once。 


[3] 使 用 const 语 法 定义 一 个 常量 


1.5 ”规则 


trait、 枚 举 或 者 类 型 别名 。 


是 允许 的 ， 但 是 使 用 define0 函 数 做 相同 的 事情 是 不 允许 的 。 


类 型 检查 器 所 执行 的 规则 非常 直 


1.5.1 ”使 用 超级 全 局 变量 


王 旦 
同文 


超级 全 局 变量 是 在 每 个 代码 范围 内 都 存在 的 全 使 


， 不 需 


global 语 
“ SGLOBALS 

* $_SERVER 

GET 

‘ $_POST 

" $FILES 

‘ $COOKIE 

“入 SESSION 


.$REQUEST 


_ENV 


句 即 可 使 


在 Hack 的 严格 模式 下 ， 并 不 支持 超级 全 
的 。 


局 变量 。 如 果 你 试 


它们 中 的 某 一 个 ， 类 下 


检查 器 将 会 告诉 你 这 个 变量 未 定义 。 然 而 在 通常 的 Web 应 


截 了 当 ， 它 的 错误 消息 被 设计 成 更 清晰 的 解释 错误 ， 并 提出 可 能 的 解决 方案 。 在 这 一 节 的 学 习 中 ， 我 们 将 会 看 到 一 些 更 加 微妙 的 案例 。 


。 这 些 在 运行 环境 中 特殊 存在 的 变量 一 共有 9 个 ， 分 别 是 : 


或 者 脚本 的 编写 过 程 中 ， 这 些 超级 变量 又 是 不 可 或 缺 


要 解决 上 述 问题 ， 你 能 够 做 的 最 简单 的 办 法 就 是 ， 在 一 个 


局 部 模式 的 文件 下 编写 访问 器 函数 ， 然 后 在 严格 模式 下 的 文件 中 调用 。 


function get params(): array { 
return $_GET; 
} 


function env vars(): array { 
return $ ENV; 
} 


// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


这 样 的 方式 对 你 代码 的 类 型 安全 不 会 有 任何 贡献 。 然 而 ， 我 们 还 可 以 做 得 更 好 。 特 别 是 对 于 HTTP 的 GET 和 POST 参 数 来 说 ， 你 经 常 知 道 所 期 待 的 值 的 类 型 ， 所 以 你 可 以 根据 这 个 知识 点 来 得 到 更 加 强健 
的 代码 : 


function string Param (string $key): ?string { 
if (!larray key exists($ GET, $key)) { 
return null; 


} 


$value = $_GET[$key]; 
return is string($value) ? $value : null; 


} 
// 或 者 选择 下 面 的 增强 版 ， 如 果 类 型 错误 将 抛 出 异常 


function string Param (string $key): ?string { 
if (!array_key_exists ($_GET，S$Skey)) { 
return null; 


} 
$value = $ GET[$key]; 


invariant (is_string ($value), 'GET param must be a string'); 
return $value; 


我 们 将 在 1.7 节 更 加 详细 地 了 解 invariant () 函数 的 使 


方法 。 目 前 来 说 ， 我 们 仅仅 需要 知道 如 果 第 一 个 参数 是 false， 它 将 会 抛 出 一 个 异常 。 


针对 其 他 的 超级 全 局 变量 和 值 类 型 ， 你 还 可 以 编写 类 似 的 访问 器 代码 。 


1.5.2 覆盖 方法 的 类 型 


在 Hack 的 代码 之 间 ， 继 承 是 更 加 复杂 的 相互 关系 中 的 一 种 。 这 复杂 性 主要 来 自 于 当 继承 关系 被 创建 时 ， 继 承 和 被 继承 的 代码 之 间 的 分 离 现 象 。 举 例 来 说 ， 如 果 你 有 个 类 型 标注 为 SomeClass 的 对 象 并 可 
以 调用 这 个 对 象 的 某 个 方法 ， 那 么 你 可 以 调用 继承 自 omeClass 的 任何 类 的 某 个 方法 。 这 个 调用 仍然 需要 是 类 型 安全 的 ， 这 就 意味 着 覆盖 其 他 方法 的 时 候 ， 方 法 的 类 型 必须 有 一 定 的 规则 。 


在 一 个 覆盖 方法 中 ， 参 数 类 型 必须 和 被 覆盖 的 方法 类 型 完全 一 致 。 这 主要 是 因为 继承 自 PHP 的 一 个 行为 。 在 PHP 中 ， 任 何 覆 盖 自 抽象 方法 或 者 接口 中 声明 的 覆盖 方法 ， 都 必须 精确 地 匹配 被 覆盖 方法 的 
参数 类 型 。 这 在 未 来 Hack 版 本 中 的 声明 可 能 会 有 所 改变 ， 多 许 改变 方法 的 参数 类 型 将 是 更 通常 的 做 法 。 


换 名 话说， 当 进行 方法 覆盖 时 ， 覆 盖 方 法 的 返回 类 型 并 不 一 定 保持 相同 ， 相 对 于 被 覆盖 的 方法 而 言 ， 履 盖 方 法 可 以 有 一 个 更 加 明确 的 返回 类 型 。 例 


class ParentClass { 
public function generate(): num { 


// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 
} 


class ChildClass extends ParentClass { 
public function generate(): int { // OK 


// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 
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仍然 是 类 型 安全 的 。 


function f(ParentClass $0bj) { 
Snumber = $0bj->generate(); 
// 即使 $obj 是 个 childclass 实 例 ，generate () 方 法 自然 会 返回 num 类 型 
// 因为 Childclass::generate() 返回 的 是 int 类 型 ， 而 所 有 int 类 型 都 属于 num 类 型 


更 通常 的 返回 类 型 进行 覆盖 是 非法 的 。 例 如 ， 如 果 ChildClass 的 generate () 方法 被 声明 成 返回 


类 型 为 mixed 的 话 ， 类 型 检查 器 将 会 报告 错误 。 


1.5.3 ”属性 值 初始 化 


为 了 维护 类 型 安全 ， 类 型 标注 过 的 属性 在 初始 化 时 ， 无 论 是 严格 模式 还 是 


局 部 模式 ， 类 型 检查 器 会 强加 一 些 规则 。 首 要 目标 就 是 确保 属性 值 在 没有 初始 化 为 正确 类 型 的 值 之 前 ， 不 能 被 读 取 。 
对 于 静态 的 属性 值 ， 规 则 非常 简单 : 任何 不 可 为 空 的 (non-nullable) 的 静态 


属性 值 都 必须 有 一 个 初始 化 值 。 没 有 显 式 初始 值 的 任何 可 为 空 的 nullable) 属性 值 将 会 被 隐 性 地 初始 化 为 null。 


非 静态 的 属性 值 将 会 有 一 套 更 加 复杂 的 规则 。 类 型 检查 器 将 确保 绝对 不 会 对 一 个 拥有 未 被 初始 化 的 不 可 为 空 的 
始 化 值 的 话 ， 都 必须 在 类 的 构造 函数 中 进行 初始 化 : 


属性 值 的 对 象 进行 实例 化 。 为 达到 这 个 目的 ， 任 何不 可 为 空 、 非 静态 的 属性 值 如 果 没 有 初 


Class Person { 
Private string $name; 
private ?string $address; 


public function _construct (string Sname) { 
$this->name = $name; 
} 
bE: 


这 个 代码 将 会 通过 类 型 检查 器 的 检查 : 属性 $name 已 经 被 恰当 地 初始 化 了 ， 并 


4$address 也 是 可 为 空 的， 那么 它 不 需要 被 初始 化 。 


类 型 检查 器 将 会 确保 在 构造 函数 中 的 所 有 代码 分 支 下 ， 所 有 的 属性 值 都 被 初始 化 。 下 面 的 代码 : 


Class Person { 
private string $name; 


public function _ construct (string $name, bool $skip name) { 
if (!$skip name) { 
$this->name = $name; 


} 


类 型 检查 器 将 会 报告 一 个 错误 : 


/home/oyamauchi/test .php:5:19,29: The class member name is not always properly 

initialized 

Make sure you systematically set $this->name when the method _construct is 

called 

Alternatively, you can define the type as optional (?http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/...) 
(NastCheck[3015]) 


对 于 类 型 检查 器 的 这 条 规则 ， 另 外 一 个 组 成 部 分 是 ， 在 构造 函数 所 有 的 属性 被 初始 化 之 前 ， 不 允许 调用 任何 公共 的 或 者 受 保护 的 方法 。 下 面 的 代码 : 


class C 1{ 
Private string $name; 


public function _construct (string Sname) { 
S$this->doSomething () 
Sthis->name = $name; 


} 


protected function doSomething(): void { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 
} 


类 型 检查 器 将 会 抛 出 一 个 错误 (不 管 怎样 ， 你 都 会 被 允许 在 $this->name 赋 值 之 后 调用 $this->doSomething () 方法 ) : 


/home/oyamauchi/test.php:6:14,18: Until the initialization of $this is over, 
you can only call private methods 

The initialization is not over because $this->name can still potentially be 
null (NastCheck[3004]) 


在 这 种 情况 下 ， 人 允许 调用 私有 方法 ， 但 是 你 所 调用 的 每 个 私有 方法 都 会 被 严格 检查 ， 以 避免 访问 到 没有 被 初始 化 的 属性 值 。 非 私有 的 方法 不 能 够 通过 这 种 方法 进行 检查 ， 因 为 它们 可 能 在 子 类 之 中 被 覆 
盖 ， 所 以 在 这 种 情形 下 ， 对 非 私有 方法 的 调用 是 非法 的 。 请 参考 下 面 的 代码 : 


class C { 
private string $name; 


public function _ construct (string Sname) { 
$this->dumpInfo () 7 
Sthis->name = $name; 


和 


private function dumpInfo(): void { 
var dump ($this->name); 
} 
LE: 


类 型 检查 器 将 会 抛 出 这 个 错误 (再 说 一 次 ， 在 $this->name 赋 值 后 允许 调用 $this->dumplnfo () 方法 ) 


/home/oyamauchi/test .php:11:21,24: Read access to $this->name before 
initialization (Typing[4083]) 


在 抽象 类 中 声明 的 属性 具有 规则 规 免 权 。 不 管 怎样 ， 具 体 的 子 类 进行 初始 化 的 时 候 都 会 要 求 初始 化 它 的 祖先 类 未 初始 化 的 属性 值 。 请 看 下 面 的 代码 : 


abstract class Abstr { 
protected string $name; 

} 

class C extends Abstr { 

i 


类 型 检查 器 将 会 抛 出 如 下 错误 : 

/home/oyamauchi/test .php:5:7,7: The class member name is not always properly 
initialized 

Make sure you systematically set $this->name When the method _ construct is 
called 


Alternatively, you can define the type as optional (?http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/...) 
(NastCheck[3015] ) 


最 后 ， 对 于 本 节 中 的 例子 ， 属 性 值 作为 构造 函数 的 一 个 参数 进行 初始 化 ， 你 可 以 使 用 构造 函数 参数 升级 (详情 请 见 3.5 节 的 内 容 ) 。 它 避免 了 公式 化 的 代码 ， 而 且 你 根本 不 必 对 属性 初始 化 的 问题 思考 什 
有 情 : 


by 
| 


class C { 
public function _ construct (private string $name) { } 


} 


1.5.4 ”可 变 参数 类 型 


正如 我 们 早期 看 到 的 一 样 ，Hack 拥 有 声明 某 个 函数 是 可 变 参数 的 语法 : 


function log error(string $format, http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/OEBPSVText/...) { 
$args = func get args(); 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 

} 


PHP 5.6 介 绍 了 一 个 不 同 的 可 变 参 数 的 语法 ， 它 有 两 个 特性 超过 了 Hack。 它 自动 把 可 变 参数 打包 成 数组 ， 人 允许 对 可 变 参 数 进行 类 型 提示 。 


function sum(SomeClass http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/...$args) { 
// $args 是 一 个 SomeClass 对 象 的 数组 
E 


这 个 语法 在 Hack 中 也 是 存在 的 。 类 型 检查 器 支持 这 个 语法 ， 并 且 类 型 检查 过 程 中 可 以 正确 调用 这 种 函数 。HHVM 也 支持 这 种 语法 ， 但 是 不 支持 类 型 标注 。HHVM 并 不 支持 检查 可 变 参 数值 的 类 型 。 当 
它 发 现 对 一 个 可 变 参数 进行 类 型 标注 的 时 候 ， 会 产生 一 个 致命 错误 ， 目 的 在 于 避免 给 人 留 下 该 类 型 标注 有 一 定 效果 的 印象 。 


这 就 产生 了 一 个 冲突 点 。 在 严格 模式 下 ，Hack 的 类 型 检查 器 不 会 允许 一 个 参数 没有 类 型 标注 ， 即 使 是 个 可 变 参数 。 但 是 HHVM 又 不 运行 对 可 变 参数 进行 类 型 标注 的 代码 。 


这 里 有 两 种 用 于 解决 该 冲突 的 可 能 方案 : 


“ 忽略 类 型 标注 ， 并 且 使 用 局 部 模式 。 


“ 忽略 类 型 标注 ， 使 用 严格 模式 ， 并 且 添 加 一 个 HH_FIXME[4033] 的 注释 信息 (详情 请 见 3.11 节 ) 。 这 是 个 推荐 的 解决 方案 ， 因 为 严格 模式 总 是 比 局 部 模式 应 该 受到 推荐 。 


1.5.5 ”和 迭代 生成 器 类 型 


对 和 迭代 生成 器 添加 一 个 返回 类 型 标注 ， 这 里 有 三 种 接口 类 型 可 以 使 用 ， 它 们 分 别 是 : lterator、Keyedlterator 和 Generator。 这 三 种 类 型 都 是 通用 的 。 在 开始 介绍 第 2 章 的 内 容 之 前 ， 我 们 不 会 
述 ， 这 里 仅仅 做 一 些 简单 的 介绍 。 


痪 


当 你 不 期 待 迭 代 在 生成 器 上 调用 send () 方法 时 ， 你 可 以 使 用 前 两 种 写法 。 当 你 只 想 yield 一 个 值 的 时 候 ， 那 么 请 使 用 lterator 作 为 返回 类 型 ， 当 你 还 同时 想 yield 到 一 个 键 的 时 候 ， 你 可 以 使 有 
Keyedlterator 作 为 返回 类 型 。 


function yields value only() : Iterator<int> { 
yield 17 
yield 27 
} 
function yields key and value(): KeyedIterator<int, string> { 


yield 1 => 'one'; 
yield 2 => 'two'; 
i 


返回 类 型 标注 |terator<int> 意 味 着 迭代 生成 器 正在 yield 的 值 是 int 类 型 ， 并 且 没 有 键 。 类 型 标注 Keyedlterator<int，string> 意 味 着 迭代 生成 器 yield 的 键 是 int 类 型 ， 而 值 是 string 类 型 的 。 这 些 定义 和 
我 们 已 知 的 数组 类 型 非常 接近 。 例 如 : array<int，string> 意 味 着 一 个 数组 它 的 key 是 个 整 型 ， 而 它 的 value 是 个 字符 捉 类 型 。 


如 果 你 将 在 这 个 迭代 生成 器 上 面 调 用 send () 方法 ， 请 使 用 Generator 标 注 : 


function has send called() : nerator<int, string, User> { 
// 空 的 yiela 操 作 ， 用 于 得 到 第 一 个 用 户 
$user = yield 0 => ''; 
// $user 的 类 型 是 ?User 


while ($user !== null) { 
$id = $user->getID(); 
$name = $user->getName (); 
$user = yield $id => $name; 
} 
} 


function main(array<User> $users): void { 
$generator = has_send called(); 
$generator->next (); 


foreach ($users as Suser) { 
$generator->send ($user); 
Var_ dump ($generator->key () ); 
Var_dump ($generator->current () ) 7 
} 
} 


返回 的 类 型 标注 Generator<int，string，User> 意 味 着 迭代 生成 器 生成 操作 得 到 的 值 是 整 型 的 ， 而 值 是 字符 串 类 型 ， 它 期 待 类 型 是 User 的 值 传递 给 它 的 send () 方法 。 


值得 注意 的 是 : 从 yield 得 到 的 结果 值 并 不 是 User 类 型 ， 而 是 ?User 类 型 。 这 是 因为 对 于 迭代 生成 器 的 调用 者 来 说 ， 它 可 能 只 是 调用 next () 方法 而 不 调用 send () 方法 。 这 就 可 能 使 从 yield 得 到 的 响 
应 值 是 null。 所 以 在 调用 它 上 面 的 方法 前 ， 必 须 检查 对 应 的 值 是 否 为 null。 详 情 请 见 1.7.1 节 的 内 容 。 


1.5.6 ”在 switch 语 句 中 的 越界 


在 switch 语 句 中 有 从 一 个 分 支 不 小 心 越界 到 另外 一 个 分 支 的 常见 错误 。Hack 添 加 了 一 条 规则 来 捕获 这 种 错误 。 下 面 将 展示 一 个 案例 ， 从 一 个 case 分 支 越界 到 另外 一 个 分 支 将 会 引发 一 个 错误 ， 除 非 第 一 
个 分 支 是 空 的 : 


switch ($day) { 
case 'sun': 
echo 'Sunday'; // 错误 
Case 'sat': 
echo 'Weekend'; 
break; 
default: 
echo 'Weekday'; 
} 


switch ($day) { 
case 'sun'; // 正确 : 这 条 语句 越界 了 ， 但 它 是 空 的 。 
Case 'sat'; 
echo 'Weekend'; 
break; 
default: 
echo 'Weekday'; 


如 果 这 个 越界 是 故意 的 ， 那 么 请 放置 注释 内 容 “//FALLTHROUGH” 到 要 穿越 分 支 的 最 后 一 行 。 


switch ($day) { 
case 'sun': 
echo 'Sunday'; 
// FALLTHROUGH 
case 'sat':; 
echo 'Weekend'; 
break; 
default: 
echo 'Weekday'; 
} 


这 对 编程 人 员 提 出 了 一 些 行动 上 的 要 求 ， 只 有 这 样 才能 更 好 地 降低 由 于 疏忽 导致 的 越界 可 能 性 。 


1.6 ”类 型 推理 


类 型 推理 对 于 Hack 的 静态 类 型 检查 来 说 是 核心 内 容 。 就 像 PHP 中 一 样 ， 本 地 变量 不 会 被 声明 为 某 个 类 型 。 然 而 ， 得 到 足够 数量 的 有 效 覆 盖 率 的 关键 就 在 于 能 够 对 本 地 变量 的 操作 进行 类 型 检查 。 


Hack 能 够 无 间隙 地 进行 类 型 推理 。 类 型 检查 器 从 一 小 组 从 标注 或 者 字面 量 上 的 已 知 类 型 入 手 ， 然 后 通过 操作 符 和 函数 调用 进行 有 效 的 跟踪 ， 然 后 顺势 对 一 切 进 行 推断 和 检查 。 


Hack 的 类 型 推理 方式 并 不 是 一 眼 就 能 看 懂 的 。 让 我 们 仔细 阅读 如 下 的 内 容 来 获得 更 多 的 细节 。 


1.6.1 没有 类 型 的 变量 


在 大 多 数 静 态 类 型 的 语言 之 中 ， 一 个 本 地 变量 出 现 后 就 会 被 定义 为 某 种 类 型 。 然 后 ， 这 个 变量 将 在 整个 生命 周期 内 保存 这 种 类 型 的 值 。 本 例 中 的 代码 可 以 是 C++ 或 者 Java， 不 论 哪 种 情况 ， 这 里 都 会 引 
发 一 个 类 型 错误 。 因 为 x 被 声明 为 一 个 int 类 型 ， 所 以 永远 不 能 把 非 int 类 型 的 值 赋值 给 它 


int x = 10; 
x = "a string"; // 错误 


这 并 不 是 一 个 Hack 中 的 例子 ， 就 像 PHP 一 样 ， 本 地 变量 在 Hack 中 可 以 不 用 声明 类 型 ， 你 可 以 简单 地 通过 赋 一 个 值 给 它 来 创建 一 个 本 地 变量 。 你 还 可 以 对 任何 本 地 变量 赋值 新 的 值 ， 而 不 用 在 意 这 个 本 
变量 原本 的 类 型 是 什么 : 


$x = 10; 
$x = "a string"; // 正确 


关键 的 不 同 点 是 : 在 Hack 中 ， 本 地 变量 本 身 是 没有 类 型 的 ， 它 所 存放 的 值 是 有 类 型 的 。 


在 本 程序 中 的 每 个 点 上 ， 类 型 检查 器 都 知道 在 那个 点 每 个 变量 所 存放 的 值 的 类 型 。 如 果 它 发 现 一 个 新 的 值 被 赋 给 了 这 个 变量 ， 那 么 它 将 及 时 更 新 关于 这 个 变量 存放 的 值 类 型 的 知识 点 。 


1.6.2 ”未 决 的 类 型 


事实 上 ， 如 果 一 个 变量 没有 类 型 定义 的 话 ， 那 就 意味 着 类 型 检查 器 需要 一 个 途径 来 处 理 下 例 中 的 代码 : 


由 


if (some condition()) { 
$x = 10, 

} else { 
$x = 'ten'; 


} 


这 种 模式 在 PHP 中 是 比较 常见 的 ， 所 以 它 在 Hack 中 也 是 合法 的 。 然 后 问题 来 了 : 在 这 个 情况 之 后 ， 类 型 检查 器 会 认为 $x 的 类 型 是 什么 呢 ? 


答案 就 是 它 使 用 了 一 个 未 决 的 类 型 (unresolved type) 。 这 是 一 个 类 型 检查 器 用 来 记 住 $x 每 个 可 能 拥有 类 型 的 结构 体 。 在 这 种 情况 下 ， 它 将 记 住 $x 可 能 是 个 整 型 ， 也 可 能 是 个 字符 串 类 型 。 


在 此 情况 之 后 ， 你 可 以 用 $x 做 任何 一 个 整 型 和 一 个 字符 捉 类 型 可 以 做 的 操作 。 当 然 你 也 不 能 做 任何 对 于 整 型 或 者 字符 捉 类 型 非法 的 操作 。 例 如 : 


if (some condition()) { 
$x = 10. 
} else { 
$x = 'ten'; 
} 
echo $x; // 成 功 : 人 人生 字符 串 类 型 
echo $x + 20; // 错 i 字符 串 类 型 ， 你 不 可 以 使 用 加 号 (加 上 整 型 ) 


echo $x->method(); // 错误 : WU 你 都 不 可 以 调用 一 个 方法 


最 重要 的 是 ，$x 将 会 满足 任何 类 型 标注 ， 包 括 整 型 和 字符 串 类 型 。 但 是 像 arraykey 和 mixed 类 型 ， 它 并 不 会 符合 : 


function takes mixed (mixed $y): void { 


function takes int(int $y): void { 


function main(): void { 


if (some condition()) { 
$x = 10, 
} else { 
$x = 'ten'; 
} 
takes int ($x); // 错误 : $x 可 能 是 个 字符 串 


takes mixed ($x); // OK 
} 


这 种 情况 也 经 常 出 现在 类 和 接口 层次 结构 上 : 


interface I 1{ 
} 
class One implements I { 
public function method(): int { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


} 
class Two implements I { 
Public function method(): string { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


} 


function main(): I { 
if (some condition()) { 
$obj = new One(); 
} else { 
S$obj = new Two(); 
} 


$int or string = $0bj->method(); // OK 


return $0obj; // OK 


在 这 里 ，$obj->method () 的 调用 是 合法 的 ， 因 为 不 管 是 类 One 还 是 类 Two， 都 有 一 个 合适 的 方法 名 和 合适 的 参数 数量 。 这 个 调用 的 返回 的 类 型 是 个 未 决 的 类 型 ，int 或 者 string 都 有 可 能 。 


return 语 句 也 是 合法 的 ， 因 为 无 论 那 种 gobj 的 可 能 性 都 符合 返回 类 型 声明 |。 


我 们 将 在 2.5 节 中 再 次 讨论 有 关 “ 未 决 的 类 型 ”的 相关 内 容 。 


1.6.3 “推理 局 限 在 函数 内 


关于 Hack 的 类 型 推理 的 一 个 最 基本 限制 就 是 : 当 分 析 一 个 函数 的 时 候 ， 它 绝对 不 会 看 另外 一 个 函数 或 方法 的 代码 体 。 举 例 来 说 ， 假 设 以 下 是 你 的 全 部 代码 : 


function fl($str) { 
return 'Here is a string: ' . $str; 


} 
function main() { 
echo f('boo!'); 


} 


main(); 


对 于 读者 来 说 ， 如 下 两 个 事实 是 非常 清晰 的 : $str 总 是 一 个 字符 串 类 型 ， 并 且 函 数 f () 总 是 返回 一 个 字符 串 。 然 而 ，Hack 的 类 型 检查 器 并 不 能 推断 出 上 述 事实 。 


一 


当 对 函数 f () 进行 类 型 推理 的 时 候 ， 它 并 不 会 检查 函数 f () 的 调用 者 以 找 出 调用 者 实际 传递 的 参数 值 的 类 型 是 什么 。 在 函数 main () 内 部 进行 类 型 推理 时 ， 它 也 不 会 查看 函数 f () 的 代码 体 来 找到 它 
实际 上 返回 的 是 什么 类 型 。 它 只 会 检查 函数 f () 的 签名 用 于 返回 类 型 标注 。 然 后 关于 函数 的 返回 类 型 标注 ， 它 什么 也 没有 发 现 ， 所 以 它 就 认为 函数 f () 的 返回 类 型 为 “any” (具体 参见 1.4.2 节 的 内 容 ) 。 


这 种 限制 的 存在 是 基于 性 能 的 原因 。 对 一 个 函数 的 推理 限制 在 这 个 函数 的 内 部 ， 是 为 了 对 这 个 函数 的 分 析 所 需要 的 计算 量 设置 一 个 严格 上 限 。 扩 展开 来 的 话 ， 就 是 对 整个 代码 库 的 所 需 计 算 量 设置 一 个 
上 限 。 在 计算 复杂 度 方面 ， 类 型 推理 算法 在 复杂 度 上 是 超 线性 (superlinear) 的 。 所 以 给 出 多 次 小 的 输入 而 不 是 一 个 巨大 的 输入 对 于 保持 运行 总 时 间 的 可 管理 性 是 非常 重要 的 。 


对 于 大 型 的 代码 库 而 言 (比如 Hack 语 言 原生 设计 的 Facebook) ， 这 个 属性 非常 重要 。 当 一 个 函数 体内 部 变化 后 〈 但 是 它 的 函数 签名 并 没有 变化 ) ， 类 型 检查 服务 端 只 需要 重新 分 析 这 个 函数 ， 然 后 保 
持 相关 的 知识 点 是 及 时 的 即 可 。 并 且 这 个 重新 分 析 的 过 程 几乎 是 实时 处 理 的 。 当 一 个 函数 签名 发 生 了 变化 后 ， 类 型 检查 器 的 服务 端 将 会 重新 分 析 这 个 函数 和 它 的 所 有 调用 者 ， 并 不 是 它们 的 调用 者 ， 这 就 对 
需要 的 工作 量 提 出 了 一 个 比较 低 的 上 限 。 


但 是 对 于 此 限制 也 有 特例 : 闭 包 。 虽 然 一 个 闭 包 从 定义 上 来 说 是 个 独立 的 函数 ， 但 是 对 一 个 内 部 有 闭 包 的 函数 进行 类 型 推理 的 时 候 ， 人 允许 对 闭 包 内 部 进行 检查 。 详 细 考 虑 一 下 如 下 示例 : 


并 推断 出 返回 
Var_dump ($doubler (10) ) 7 // :int(20) 
var dump ($doubler (3.14)); // float(6.28) 


虽然 这 个 闭 包 没有 任何 的 返回 类 型 标注 (这 在 严格 模式 下 也 是 合法 的 ) ， 类 型 检查 器 依然 能 够 推断 出 $doubler (10) 是 个 整 型 。 这 是 因为 它 分 析 了 闭 包 的 函数 体内 部 的 内 容 ， 在 $x 是 个 整 型 的 假设 下 ， 
并 且 在 两 个 整 型 上 应 用 加 号 操作 符 ， 仍 然 会 得 到 一 个 整 型 结果 [1]。 同 理 ， 它 可 以 推断 出 $doubler (3.14) 是 浮 点 数 类 型 。 


顺便 提 一 下 ， 正 是 因为 类 型 推理 能 够 对 闭 包 内 部 进行 推理 ， 所 以 即使 在 严格 模式 下 ， 也 人 允许 闭 包 没 有 类 型 标注 。 


四 除非 它 不 是 ， 详 见 3.8 节 的 内 容 。 


1.7 ”类 型 提炼 


假设 你 有 个 ? string 类 型 的 值 ， 而 且 准 备 把 这 个 值 传递 给 一 个 参数 类 型 为 string 的 函数 。 那 么 你 怎么 把 一 个 类 型 (? string) 转化 为 另外 一 个 类 型 (string) 呢 ? 或 者 假设 你 有 个 object 类 型 的 值 ， 它 可 
能 实现 或 没有 实现 Polarizable 接 口 。 同 时 ， 如 果 它 实现 了 这 个 接口 ， 你 还 希望 调用 这 个 object 的 方法 polarize () 。 那 么 类 型 检查 器 如 何 才能 知道 polarize () 调用 是 合法 的 ? 


在 一 个 良好 组 织 的 代码 中 ， 实 现 一 个 值 是 一 个 类 型 同时 又 是 另外 一 个 类 型 的 任务 情况 非常 常见 。 这 些 看 起 来 非常 琐碎 的 事情 是 你 必须 拿 来 安抚 类 型 检查 器 的 关键 所 在 。 这 是 Hack 能 够 在 开发 前 期 就 捕获 
问题 的 关键 。 这 也 是 Hack 能 够 避免 像 调 用 一 个 不 存在 的 方法 、 在 不 恰当 的 地 方 找到 了 一 个 空 值 ， 以 及 其 他 一 些 在 PHP 代 码 库 开 发 调试 中 常见 的 恼人 错误 这 些 情况 的 原因 。 


你 有 三 种 类 型 检查 器 使 用 的 方式 对 这 些 类 型 进行 提炼 转化 ， 它 们 是 : 是 否 为 空 检查 、 类 似 is_integer () 的 内 置 类 型 查询 函数 ， 以 及 instanceof。 当 这 些 语 句 在 流程 控制 语句 (比如 循环 语句 、 条 件 语 
句 ) 中 被 使 用 时 ， 类 型 推理 引擎 将 会 明确 知晓 : 在 不 同 的 流程 控制 路 径 下 ， 类 型 值 也 不 同 。 


1.7.1 提炼 nullable 类 型 到 non-nullable 类 型 


null 检 查 语 名 在 从 空 值 (nullable) 的 类 型 到 非 空 值 (non-nullable) 类 型 的 转变 中 经 常用 到 。 下 面 是 个 通过 了 类 型 检查 器 检查 的 示例 。 


function takes string(string $str) { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 
function takes nullable string(?string $str) { 
if ($str !== nu1l) { 
takes_ string ($str); 


} 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


在 if 语 句 段 内 部 ， 类 型 检查 器 知道 $str 是 个 非 空 值 ， 所 以 它 能 够 传递 给 函 takes_string () 。 注 意 null 检 查 应 该 使 用 恒 等 操 作 符 === 和 ! ==， 而 不 是 普通 的 等 于 操作 符 (== 和 ! =) ， 或 者 转化 为 一 个 
boolean 类 型 。 如 果 你 不 用 恒 等 符号 ， 类 型 检查 器 会 报告 一 个 错误 [0]。 内 置 的 函数 js_null () 也 是 可 以 工作 的 。 下 面 是 三 元 表达 式 的 例子 : 


function takes nullable string(?string $str) { 

takes string($str 一 = null ? "(nuvl1l)" ; $str); 

// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 


当然 你 还 可 以 使 用 如 下 的 样式 ， 即 把 一 个 分 支流 直接 切断 : 


function processInfo(?string $info) { 


if ($info 一 = null) { 
return; 

. 

takes_string ($info); 


} 


类 型 检查 器 知道 ， 对 函数 takes string () 的 调用 仅仅 当 $info 变 量 不 为 空 时 才 会 被 执行 。 因 为 如 果 它 为 空 ，if 代 码 段 将 会 进入 ， 然 后 函数 会 直接 返回 。 (如 果 return 语 句 改 成 throw 语 句 ， 效 果 是 一 样 


的 。) 
如 下 是 个 更 大 的 例子 ， 展 示 了 一 个 更 加 复杂 敏感 的 流程 控制 : 
function fetch from _ cache () : ?string 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 
function do expensive computation(): string { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 
function get datal(): string { 
$result = fetch from cache(); 
if ($result = Roll { 
$result = do_expensive computation(); 
} 
return $result; 
} 
在 return 语 句 这 里 ， 类 型 检查 器 知道 $result 是 个 非 空 的 值 ， 所 以 返回 类 型 标注 就 被 满足 了 。 如 果 if 代 码 段 进入 ， 那 么 一 个 非 空 的 字符 捉 将 会 分 配给 $result。 如 果 if 代 码 段 没有 进入 ， 那 么 $result 必须 已 
经 是 非 空 的 字符 串 。 
最 后 ，Hack 有 个 特殊 内 置 的 函数 叫做 invariant () ， 你 可 以 使 用 这 个 函数 来 向 类 型 检查 器 陈述 事实 。 这 个 函数 使 用 两 个 参数 ， 一 个 是 boolean 的 表达 式 ， 另 一 个 是 字符 串 类 型 ， 主 要 用 来 向 读者 描述 问 
题 所 在 : 


function ProcessInfo (?string $info) { 
invariant ($info !== null, "I know it's never null somehow"); 
takes string ($info); 

} 


在 运行 环境 中 ， 如 果 invariant () 的 第 一 个 参数 值 被 证 明 是 false， 那 么 一 个 不 变异 常 (InvariantException) 将 会 触发 。 类 型 检查 器 知道 这 并 且 推断 出 : 在 invariant () 函数 后 面 的 调用 中 ，$info 不 


会 是 个 空 值 。 否 则 的 话 ， 一 个 异常 早 就 被 她 出 了 ， 而 代码 根本 就 不 会 执行 到 这 个 地 方 。 


1.7.2 ”提炼 mixed 类 型 到 原始 类 型 


识 点 将 在 你 检测 mixed 类 型 和 泛 型 时 用 到 。 


内 


对 每 个 原始 类 型 来 说 ， 这 里 有 内 置 的 函数 来 检测 一 个 变量 是 否 为 原始 类 型 (比如 is_integer () 、is_string () 、is_array () ) 。 类 型 检查 器 特别 识别 出 这 些 函 数 ， 除 了 is_object () 四 之 外 。 这 个 知 


你 使 用 这 些 内 置 的 函数 来 传递 信息 给 类 型 检查 器 的 方式 ， 和 你 使 用 null 检 查 的 方式 非常 接近 。 类 型 检查 器 控制 敏感 的 流程 ， 你 可 以 使 用 invariant () 等 。 然 而 ， 这 些 内 置 函数 携带 的 信息 比 “ 空 或 者 非 


”更 复杂 。 所 以 这 里 我 们 对 它们 如 何 工 作 做 更 加 细致 的 探讨 。 


首先 ， 类 型 检查 器 不 会 记 住 任何 负面 的 信息 ， 例 如 “这 个 值 不 是 个 字符 串 类 型 ”。 请 看 如 下 示例 : 


function f(mixed Sval) { 
if (!is string($val)) { 
// 这 里 $val 是 个 mixed 类 型 我 们 并 不 记得 它 不 是 一 个 字符 串 
} else { 
// 这 里 $val 是 个 字符 串 类 型 
} 
} 


在 具体 的 实践 中 ， 这 问题 不 大 。 如 果 我 们 知道 一 个 值 可 能 是 任何 类 型 而 不 是 字符 串 的 话 ， 用 途 是 非常 小 的 。 除 非 在 将 来 能 够 对 它 进 一 步 提 炼 。 


其 次 ， 内 置 的 类 型 查询 功能 是 唯一 的 提炼 类 型 到 原始 类 型 的 办 法 。 甚 至 对 目前 已 知 类 型 的 值 做 身份 对 比 也 无 法 实现 它 : 


function f(mixed $val) { 
if ($val === 'some string') { 
// 这 里 $val 是 个 mixed 类 型 _ 
// 只 有 :is_string 可 以 告知 类 型 检查 器 ， 它 是 个 字符 串 
} 
} 


1.7.3” 对象 类 型 提炼 


最 终 ， 类 型 检查 器 会 明白 使 用 instanceof 来 检查 某 个 object 是 否 为 给 定 类 或 接口 的 实例 。 就 像 null 检 查 和 内 置 的 类 型 查询 一 样 ， 类 型 检查 器 明白 条 件 语句 和 invariant () 中 的 instanceof 语 句 : 


class ParentClass { 


} 


class ChildClass extends ParentClass { 
public function dochildThings () : void { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


} 


function doThings (ParentClass $ob]j) : void { 
if ($obj instanceof Childclass) { 
S$cbj->dochildThings (); // OK 
和" 
} 


function unconditionallyDoThings (ParentClass $0obj): void { 
invariant ($obj instanceof ChildClass, 'just trust me'); 
S$obj->dochildThings (); // OK 

} 


这 里 将 会 有 更 多 的 细节 ， 并 不 像 null 检 查 和 内 置 类 型 查询 功能 ，instanceof 在 处 理 类 型 方面 能 够 以 更 复杂 的 方式 重 苹 使 用 ， 但 是 类 型 检查 器 导航 它们 的 能 力 的 确 有 小 的 限制 。 


下 面 的 例子 将 会 展示 这 个 限制 ， 我 们 有 个 抽象 类 型 的 基 类 ， 同 时 有 很 多 子 类 。 这 些 子 类 中 ， 有 些 实现 了 内 置 的 接口 Countable， 但 有 些 并 没有 实现 : 


abstract class BaseClass { 
abstract public function twist(): void; 
} 


class CountableSubclass extends BaseClass implements Countable { 
public function count(): int { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


public function twist(): void { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


} 


class NonCountableSubclass extends BaseClass { 
public function twist(): void { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


然后 我 们 有 个 拿 BaseClass 做 参数 类 型 的 函数 ， 如 果 传 入 的 参数 是 Countable 的 话 ， 我 们 就 调用 函数 count () ， 然 后 调用 一 个 在 BaseClass 里 面 声明 的 方法 。 这 在 面向 对 象 的 代码 库 中 是 非常 常见 的 模 
式 ， 不 仅仅 局 限于 Countable 接 口 : 


function twist and count (BaseClass $0bj): void { 
if ($0bj instanceof Countable) { 
echo "Count: ' . $0bj->count(); 


} 
S$obj->twist (); 
} 


最 后 一 行将 会 有 个 类 型 错误 ， 这 似乎 是 完全 出 平 意料 的 ， 所 以 让 我 们 来 了 解 一 下 这 个 问题 的 细节 所 在 。 


理解 这 个 错误 的 关键 在 于 ， 当 类 型 检查 器 看 到 一 个 instanceof 检 查 的 时 候 ， 它 所 传递 的 信息 将 会 是 非常 严格 的 和 类 型 检查 一 致 的 信息 ， 它 不 会 考虑 继承 的 层次 结构 、 接 口 ， 或 者 任何 其 他 的 因素 。 它 甚 
至 有 可 能 不 满足 相关 的 条 件 (比如 BaseClass 及 其 继承 类 们 并 没有 实现 Countable 接 口 ) ， 但 是 类 型 检查 器 不 这 么 认为 。 


在 函数 的 开始 部 分 ， 类 型 检查 器 由 于 类 型 标注 的 缘故 ， 会 认为 $obj 的 类 型 是 BaseClass。 然 而 在 if 代码 段 内 ， 类 型 检查 器 会 认为 gobj 是 Countable 类 型 的 ， 而 不 是 一 个 实现 了 Countable 接 口 的 
BaseClass 实 例 。 它 会 忘记 $obj 在 是 Countable 的 同时 ， 还 是 一 个 BaseClass。 


然后 我 们 进入 if 代码 段 后 面 的 部 分 。 这 里 ，$obj 的 类 型 是 个 包含 BaseClass 或 者 Countable 的 未 决 的 类 型 (详情 请 见 1.6.2 节 的 内 容 ) 。 然 后 当 类 型 检查 器 看 到 了 代码 gobj->twist () 的 时 候 ， 它 报告 了 
一 个 错误 ， 因 为 它 认为 有 可 能 在 此 调用 中 $obj 的 值 是 非法 的 ， 比 如 它 是 Countable 类 型 而 不 是 BaseClass 类 型 。 当 然 你 作为 读者 ， 知 道 这 是 不 可 能 的 。 但 是 类 型 检查 器 不 行 。 


解决 这 个 问题 的 方法 就 是 对 于 instanceof 检 查 使 用 一 个 独立 的 本 地 变量 。 这 就 可 以 阻止 类 型 检查 器 丢失 $obj 的 类 型 信息 ， 这 才 是 这 个 问题 的 根源 : 


function twist and count (BaseClass $0bj) { 
S$obj countable = $0bj; 
if (Sobj countable instanceof Countable) { 
echo 'Count: ' . $0bj countable->count () 


} 
S$obj->twist (); 


内 在 上 面 描述 的 所 有 情形 中 ， 在 if 语句 或 者 invatiant () 函数 调用 中 ， 必 须 是 一 个 单独 的 类 型 查询 。 使 用 或 逻辑 操作 符 “||” 的 联合 多 类 型 查询 是 不 被 类 型 检查 器 支持 的 。 正 如 下 例 所 示 ， 这 将 会 有 个 类 
型 错误 : 


Class Parent { 

} 

class One extends Parent { 
public function go(): void {} 

E 

class Two extends Parent { 
public function go(): void {} 

} 


function fl(Parent $0obj): void { 
if ($0bj instanceof One || $obj instanceof Two) { 
$obj->go (); // 错误 

} 


一 个 非常 好 的 解决 办 法 就 是 使 用 接口 。 创 建 一 个 接口 然后 声明 一 个 go () 方法 ， 让 One 和 Two 来 实现 它 ， 然 后 在 函数 f () 中 对 这 个 接口 进行 检查 。 


1.7.4 ”属性 值 推理 


目前 为 止 , 我 们 所 有 示例 中 的 推理 都 是 基于 本 地 变量 的 。 这 很 容易 


因为 类 型 检查 器 能 够 确信 ， 它 能 够 看 到 所 有 本 地 变量 的 读 和 写 操作 B]。 所 以 它 在 对 本 地 变量 进行 类 型 推理 时 ， 能 够 做 出 较 强 的 担 
保 。 


| 
性 


属性 值 的 推理 是 更 加 困难 的 。 困 难 的 根源 在 于 本 地 变量 在 它 所 在 的 函数 外 部 无 法 修改 ， 但 是 属性 值 可 以 。 请 分 析 下 面 的 例子 : 


function increment check count () : void { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
i 


function check for valid characters (string $name): void { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


Class C { 
private ?string $name; 
public function checkName () : void { 
if ($this->name !== null) { 
increment_ check count () 7 
check for valid characters ($this->name); 
} 
” 
} 


这 段 代 码 并 不 能 通过 类 型 检查 器 ， 将 会 报告 如 下 的 错误 : 


/home/oyamauchi/test .php:16:34,44: Invalid argument (Typing[4110]) 
/home/oyamauchi/test .php:6:37,42: This is a string 
/home/oyamauchi/test .php:11:11,17: It is incompatible with a nullable type 


/home/oyamauchi/test .php:15:7,29: All the local information about the member 
name has been invalidated during this call. 
This is a limitation of the type-checker, use a local if that's the problem. 


错误 将 会 指向 对 函数 check_for_valid_characters () 的 调用 。 错 误 信息 给 出 了 一 个 对 错误 的 简单 解释 。 在 null 检 查 后 ， 类 型 检查 器 知道 $this->name 并 不 为 空 ， 然 而 ， 对 函数 
increment_check_count () 的 调用 执行 迫使 类 型 检查 器 忘记 了 $this->name 不 为 空 的 结论 ， 因 为 事实 可 能 由 于 调用 的 结果 而 改变 。 


你 作为 一 名 程序 员 ， 可 能 知道 $this->name 的 值 不 会 因为 调用 increment_check_count () 函数 的 结果 而 改变 ， 但 是 类 型 检查 器 自己 不 能 发 现 这 点 。 正 如 我 们 看 到 的 那样 ， 推 理 是 基于 本 地 函数 的 。 正 
如 错误 信息 所 说 的 一 样 ， 解 决 方法 就 是 使 用 本 地 变量 。 复 制 属性 值 到 一 个 本 地 变量 ， 然 后 使 用 这 个 本 地 变量 进行 替换 : 


public function checkName () : void { 
if (Sthis->name !== null) { 
$local name = $this->name; 
Logger: :1og('checking name: . $local name); 
check for valid characters ($local name); 
} 


你 还 可 以 在 if 代码 段 之 外 写本 地 变量 的 复制 语句 。 然 对 本 地 变量 进行 null 检 查 。 无 论 如 何 ， 都 必须 让 类 型 检查 器 确认 $local name 没有 被 修改 ， 然 后 它 就 能 记 住 类 型 非 空 的 推断 了 。 


四 这 是 因为 ， 比 如 null=="0" 为 真 ， 这 将 使 得 null 检 查 的 结果 有 些 荒 绿 。 
四] 这 是 因为 对 于 resource 来 说 ，is_object0 返 回 真 。 在 实践 之 中 ， 缺 乏 对 is_object0 函 数 的 支持 并 不 是 个 问题 。 因 为 对 于 一 个 object， 如 果 不 知 道 它 的 具体 类 型 ， 你 不 能 做 任何 事情 。 
正如 我 们 看 到 的 那样 ， 类 型 检查 器 会 假装 引用 并 不 存在 。 如 果 你 把 一 个 局 部 变量 作为 一 个 引用 参数 值 传递 到 一 个 函数 中 ， 类 型 检查 器 会 假设 它 不 会 改变 。 


1.8 ”运行 环境 中 的 类 型 标注 的 执行 


在 一 个 Hack 代 码 库 中 ， 即 使 类 型 检查 器 并 没有 报告 错误 ， 但 是 在 运行 环境 仍然 可 能 有 错误 发 生 。 这 种 情况 最 明显 的 情形 就 是 通过 耦合 模式 : 因为 在 耦合 模式 下 ， 代 码 并 不 会 进行 类 型 检查 。 所 以 对 函数 
的 调用 传递 了 错误 类 型 的 参数 值 ， 也 是 有 可 能 的 。 


在 未 来 的 发 布 版 本 中 ，HHVM 的 运行 环境 类 型 检查 将 会 更 加 严格 ， 但 是 目前 的 版 本 中 ， 在 运行 环境 中 对 类 型 标注 的 检查 只 是 部 分 支持 。 


首先 ，HHVM 会 忽略 属性 值 的 类 型 标注 ， 你 可 以 对 一 个 类 型 标注 的 属性 赋予 任何 喜欢 的 值 。HHVM 并 不 会 抱怨 。 


参数 的 类 型 标注 行为 和 PHP 的 类 型 提示 的 一 样 ， 一 旦 违反 了 规则 ， 一 个 可 捕捉 的 致命 错误 将 会 产生 [1]。 对 返回 类 型 标注 也 是 一 样 的 。 


违反 规则 时 ， 你 可 以 把 任何 参数 或 者 返回 类 型 标注 产生 的 致命 错误 变 成 一 个 警告 错误 ， 方 法 就 是 在 最 前 面 加 个 @ 符 号 。 这 称 为 一 个 软 (soft) 标注 。 对 于 已 经 存在 的 代码 添加 新 的 标注 时 ，“ 软 标 
注 ”仅仅 是 个 过 渡 性 的 措施 (具体 参见 10.2.2 节 的 内 容 ) 。 最 好 不 要 在 新 代码 中 使 用 它 ， 而 对 于 已 经 存在 的 硬 标注 ， 当 然 也 不 要 改 成 “ 软 ” 的 。 


对 于 参数 类 型 标注 和 返回 类 型 标注 来 说 ，Hack 类 型 标注 的 一 些 细节 并 没有 被 执行 : 

“ 任何 对 原始 类 型 、object 类 型 、num 或 者 atraykey 的 标注 都 是 按 原 型 执行 的 。 

“ 返回 类 型 void 并 没有 被 执行 。 这 就 是 说 ， 如 果 一 个 函数 的 返回 类 型 是 void， 那 么 它 可 以 返回 一 个 真实 的 值 ， 这 在 程序 真正 运行 时 并 不 会 引发 任何 错误 。 
“ 对 于 tuple 和 shape 的 标注 就 是 array。 内 部 的 类 型 并 没有 检查 。 

“ 枚 举 标 注 被 执行 检查 ， 就 好 像 它们 是 枚 举 基 础 类 型 一 样 。 在 运行 环境 中 ， 值 并 没有 被 检查 ， 以 确保 它们 是 枚 举 的 合法 值 。 

. 泛 型 标注 并 没有 和 它 的 类 型 形 参 一 起 被 执行 检查 。 这 就 是 说 ， 一 个 array<stting，MyClass> 的 类 型 标注 被 执行 为 array， 内 部 类 型 并 没有 被 检查 。 

“ nullable 类 型 被 正确 检测 了 。 


[中 “可 捕 提 的 致命 错误 ” 听 起 来 有 些 了 矛盾， 这些 错 误 有 着 非常 奇怪 的 行为 : 捕获 这 些 错误 唯一 的 方式 就 是 使 用 用 户 自 定义 的 错误 处 理 程序 ， 你 可 以 使 用 内 置 函 数 set_error handler0 来 进行 设置 。 


第 2 章 泛 型 


泛 型 在 Hack 的 类 型 系统 里 面 是 个 非常 强大 的 特性 ， 泛 型 可 以 允许 你 在 不 知道 流程 中 传 入 的 具体 类 型 的 情况 下 ， 写 出 类 型 安全 的 代码 。 一 个 类 或 者 函数 都 可 以 是 泛 型 的 ， 这 意味 着 它 可 以 让 调用 者 来 选择 
传 入 的 参数 类 型 。 


泛 型 结构 体 最 好 的 例子 就 是 数组 和 集合 类 (关于 集合 类 的 更 多 内 容 请 参见 第 5 章 ) 。 不 具备 明确 指出 数组 内 容 具 体 类 型 的 能 力 ， 它 不 可 能 推断 出 索引 自 数组 的 任何 值 的 类 型 ， 并 且 设置 数组 中 的 一 个 值 不 
能 被 类 型 检查 。 这 些 操作 在 PHP 和 Hack 中 都 是 非常 常见 的 ， 并 且 泛 型 让 类 型 检查 器 能 够 理解 并 对 它们 进行 核实 。 


在 本 章 的 内 容 中 ， 我 们 将 对 泛 型 提供 的 所 有 特性 进行 查看 和 学 习 。 


2.1 入 门 实例 


我 们 将 会 从 一 个 非常 简单 的 例子 入 手 学 习 : 一 个 包含 随意 值 的 类 。 你 可 能 在 日 常 练习 中 从 来 没有 这 么 写 过 这 样 的 代码 [1]， 但 是 这 是 一 个 对 泛 型 进行 介绍 的 最 好 例子 。 在 本 章 的 学 习 中 ， 我 们 讲 会 使 用 它 
作为 运行 的 实例 。 


为 了 使 一 个 类 “ 泛 型 化 ”， 我 们 可 以 在 类 名 后 面 放置 一 个 由 尖 括 号 括 起 来 的 、 逗 号 分 隔 的 类 型 形 参 列表 。 一 个 类 型 形 参 可 以 简单 理解 为 : 一 个 用 大 写 T 开 头 的 标识 符 。 在 泛 型 类 定义 内 部 ， 可 以 在 变量 标 
准 中 使 用 这 些 类 型 形 参 。 主 要 在 如 下 三 个 常见 的 位 置 (属性 、 方 法 形 参 、 方 法 的 返回 标注 类 型 ) 。 


下 面 是 泛 型 类 的 例子 : 


class Wrapper<Tval> { 
private Tval $value; 


public function _ construct (Tval $value) { 


Sthis->value = $value; 


} 


public function setValue (Tval $value): void { 
$this->value = $value; 


} 


public function getValue(): Tval { 
return S$this->value; 
} 


// There can be multiple type parameters 
class DualWrapper<Tone, Ttwo> { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


为 了 使 用 这 种 泛 型 类 ， 你 仅 需要 像 往常 一 样 对 它 进 行 实例 化 ， 然 后 使 用 得 到 的 结果 对 象 即 可 。 


S$wrapper = new Wrapper (20) 
$x = $wrapper->getValue (); 


在 这 个 例子 中 ， 得 益 于 Wrapper 是 泛 型 的 ， 所 以 类 型 检查 器 知道 $x 是 个 整数 。 它 能 够 看 到 你 传递 了 整数 到 Wrapper 的 构造 函数 中 ， 并 且 推 断 出 它 应 该 对 这 个 特殊 的 Wrapper 实 例 的 使 用 进行 类 型 检查 ， 
就 好 像 把 类 定义 中 所 有 的 Tval 用 int 进 行 替 代 一 样 。 


在 这 种 情况 下 ， 类 型 检查 过 程 和 你 用 下 面 的 这 个 类 对 Wrapper 类 进行 替代 得 到 的 效果 一 样 好 。 


class WrapperOfInt { 
private int $value; 


public function _ construct (int $value) { 
$this->value = Svalue; 


A 


public function setValue (int $value): void { 
$this->value = $value; 


} 


public function getValue(): int { 
return S$this->value; 
} 
} 


然而 ， 对 于 泛 型 版 本 ， 你 可 以 对 这 个 类 使 用 任何 类 型 ， 这 具有 明显 的 益处 。 如 果 你 传递 一 个 字符 串 类 型 到 Wrapper 类 的 构造 函数 中 ， 那 么 这 个 实例 的 getValue () 方法 的 返回 类 型 也 会 是 个 字符 串 。 你 
如 果 你 传递 一 个 ? float 类 型 的 值 到 Wrapper 的 构造 函数 中 ， 那 么 该 实例 的 getValue () 方法 的 返回 类 型 也 将 是 ? float。 诸 如 此 类 ， 你 可 以 对 能 想得到 的 其 他 类 型 进行 类 似 推 理 判断 。 


这 就 是 泛 型 的 真实 力量 : 你 可 以 对 Wrapper 类 写 一 个 包含 任何 类 型 值 的 单独 实现 ， 但 是 它 仍然 是 彻底 类 型 安全 的 。 


作为 本 次 说 明 的 最 后 部 分 ， 这 里 将 介绍 如 何 为 一 个 泛 型 类 的 实例 写 一 个 类 型 标注 。 语 法 是 一 个 类 名 ， 随 后 跟随 着 被 尖 括 号 括 起 来 的 、 喜 号 分 隔 的 类 型 标注 列表 。 在 列表 中 的 每 个 标注 都 被 称 作 类 型 实 
参 : 


function wrapped input () : Wrapper<string> { 
$input = readline ("Enter text: ") 7 
return new Wrapper ($input); 


} 


类 型 形 参 (type parameter) 和 类 型 实 参 (type argument) 的 关系 就 和 函数 形 参 (function parameter) 和 函数 实 参 (function argument) 的 关系 一 样 。 类 型 实 参 是 泛 型 类 定义 中 的 类 型 形 参 在 具 
体 使 用 时 的 某 代 品 。 在 本 例 中 ， 函 数 返 回 值 是 Wrapper 类 的 一 个 实例 ， 它 将 告诉 类 型 检查 器 应 该 对 这 个 对 象 的 使 用 进行 类 型 检查 ， 就 好 像 对 该 类 定义 中 的 所 有 Tval 茶 换 为 string。 


[ 它 并 不 是 像 它 表面 上 看 到 的 那么 无 用 ， 它 是 一 个 模拟 原始 类 型 引用 语法 非常 好 的 途径 。 这 在 Hack 中 将 比 在 PHP 中 更 加 有 用 ， 因 为 PHP 风 格 的 引用 在 Hack 中 是 被 禁止 的 。 


2.2 ”其 他 泛 型 实体 
类 并 不 是 唯一 可 以 被 泛 型 化 的 实体 。 


2.2.1 ”函数 和 方法 


泛 型 函数 在 它 的 名 字 和 参数 列表 的 在 圆 括号 之 间 有 类 型 形 参 的 列表 。 并 且 它 可 以 像 往 常 一 样 被 调用 ， 请 看 下 面 的 例子 : 


function wrap<T>(T $value): Wrapper<T> { 
return new Wrapper ($value); 


} 


function main(): void { 
$w = wrap (20); 
i 


就 像 这 个 例子 所 示 ， 泛 型 函数 的 类 型 形 参 能 够 在 函数 的 形 参 类 型 和 返回 类 型 这 两 个 地 方 使 


方法 也 可 以 是 泛 型 的 。 如 果 一 个 方法 存在 于 一 个 泛 型 类 或 者 trait 中 ， 它 能 够 使 用 其 闭合 类 的 类 型 形 参 ， 如 下 所 示 : 


Class Logger { 
public function logWrapped<Tval> (Wrapper<Tval> $value): void { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


} 
Class Processor<Tconfig> { 


Public function checkValue<Tval> (Tconfig $config, Tval $value): bool { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


2.2.2 trait 和 接口 


trait 和 接口 两 者 都 可 以 是 泛 型 的 。 语 法 和 泛 型 类 的 语法 非常 相似 ， 都 是 在 名 称 后 面 放置 类 型 形 参 的 列表 : 


trait DebugLogging<Tval> { 
Public static function debugLog (Tval $value): void { 


// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


} 
} 


interface WorkItem<Tresult> { 
public function performWork(): Tresult; 
} 


任何 使 用 一 个 泛 型 trait 或 者 实现 一 个 泛 型 接口 的 代码 ， 都 必须 特别 指明 相关 的 类 型 实 参 : 


class StringProducingWorkItem implements WorkItem<string> { 
use DebugLogging<string>; 


// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


泛 型 类 可 以 传递 它 的 类 型 形 参 到 它 所 实现 的 接口 类 型 或 使 用 的 trait 中 。 


class ConcreteWorkItem<Tresult> implements WorkItem<Tresult> { 
Use DebugLogging<Tresult>; 


// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


2.2.3 ”类 型 别名 


关于 类 型 别名 的 详细 内 容 请 参见 3.2 节 的 内 容 。 它 们 能 够 通过 立即 添加 类 型 形 参 列 表 到 它们 别名 后 而 完成 泛 型 化 。 


type matrix<T> = array<array<T>>; 


这 里 有 一 个 关于 类 型 别名 的 非常 有 意思 的 泛 型 程序 ， 在 这 个 程序 中 ， 你 将 不 会 在 右边 的 位 置 上 使 用 类 型 形 参 。 最 好 的 示例 就 是 序列 化 : 


newtype serialized<T> = string; 


function typed serialize<T>(T $value): serialized<T> { 


return serialize ($value); 


} 


function typed unserialize<T> (serialized<T> $value): T { 


return unserialize ($value); 


i 


鉴于 普通 的 没有 类 型 声明 的 serialize () API 会 丢失 有 关 序 列 化 值 类 型 的 相关 信息 ， 这 个 别名 使 类 型 检查 器 在 大 量 类 型 的 序列 化 版 本 中 可 以 进行 分 辨 。 这 在 类 型 检查 器 中 并 不 会 引发 错误 ， 这 是 因为 本 质 


上 来 说 ， 类 型 检查 器 并 没有 对 它 进 行 检查 : unserialize () 函数 没有 返回 类 型 标注 ， 所 以 类 型 检查 器 只 是 简单 地 相信 它 所 做 的 


在 这 里 ， 类 型 检查 器 知道 unserialized 变 量 是 字符 串 类 型 。 


有 情 ， 并 且 相 关 返 回 值 也 是 正确 的 (请 参见 1.4.2 节 ) 。 


$serialized str = typed serialize ("hi"); 
S$unserialized = typed unserialize ($serialized str); 


你 还 可 以 对 每 个 序列 化 的 值 类 型 进行 检查 ， 以 保证 相关 的 变量 类 型 。 


function process names (serialized<array<string>> $arr): void { 


foreach (typed unserialize ($arr) as $name) { 


// 这 里 的 Sname 已 被 确认 为 字符 串 


// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


} 


E 


2.3 ”类 型 消除 


泛 型 是 非常 纯正 的 类 型 检查 器 级 别 的 结构 体 ，HHVM 几乎 完 全 不 知道 它 的 存在 [1]。 


| 


型 消除 (type erasure) 。 


对 于 泛 型 实体 定义 内 的 类 型 形 参 ， 这 里 有 “关于 你 什么 能 做 及 什么 不 能 做 的 ”的 重要 结论 。 
情 。 例 如 : 


“ 进行 实例 化 ， 例 如 new 工 () 。 


“ 把 它 当 作 作 用 域 使 用 ， 例 如 T: : someStaticMethod () 、T: : $someStaticProperty， 或 T: 


. 把 它 当 作 类 型 实 参 ， 例 如 : 在 function f<T> (T<mixed>$value) 中 。 


' 把 它 放 置 在 instanceof 的 右边 ， 例如: 在 $value instanceof 中 。 


“ 强制 转化 为 该 类 型 ， 例 如 : 在 (T) $value 中 。 


“ 在 catch 代 码 段 中 在 一 个 类 名 的 位 置 使 用 它 ， 例 如 : 


: SOME_CONSTANT。 


对 于 类 型 形 参 ， 你 唯一 能 做 的 一 件 事 是 在 类 型 标注 中 使 


有 实 上 ， 当 HHVM 运 行 一 段 泛 型 代码 的 时 候 ， 真 实 的 效果 就 像 反 所 有 的 类 型 形 参 和 类 型 实 参 都 去 除 。 这 种 行为 称 为 类 


它 。 这 里 你 不 能 对 类 型 形 参 做 某 些 其 


他 类 型 可 以 的 


function f<Texc>(): void { 


try 4 
something that throws(); 


} catch (Texc $exception) {??// 错误 


// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


} 


“ 在 一 个 静态 属性 值 的 类 型 上 使 用 它 ， 例 如 : 


class SomeClass<T> { 
// 也 是 非法 的 ， 因 为 这 个 属性 并 没有 初始 化 ， 
// 但 这 里 并 没有 可 能 的 任何 合法 初始 值 
public static T $property; 

} 


当 类 型 形 参 被 


作 类 型 标注 时 ， 它 们 在 运行 环境 中 并 非 是 强制 实现 的 。 在 本 例 中 ， 我们 使 


了 耦合 模式 ， 


因此 在 函数 f () 内 的 方法 调 


上 类 型 检查 器 不 会 报告 任何 错误 。 


<?hh //ded 

class GenericClass<T> { 
public function takes type param(T $x): 
} 


void { 


public function takes int (int $x) 
‘ 
} 


3 void 4t 


function f(GenericClass<int> $gc): 
// 下 面 的 所 有 调用 都 会 有 类 型 检查 错误 
// 但 这 个 文件 是 解 耦 模式 的 
// 没有 运行 时 错误 
$gc->takes type param('a string'); 
// 运行 时 错误 :可 捕获 的 致命 错误 


$gc->takes int('a string'); 


void { 


中 唯一 的 异常 来 自 于 异步 函数 的 返回 类 型 。 参 见 第 6 章 的 内 容 。 


2.4 约束 


在 泛 型 实体 的 定义 内 ， 类 型 检查 器 对 于 类 型 形 参 一 无 所 知 ， 这 是 掌握 泛 型 类 型 的 要 点 所 在 。 


方法 或 者 访问 属性 ， 不 能 对 它 进行 索引 ， 不 和 角 


当然 ， 可 以 通过 对 类 型 形 参 
关于 Wrapper 类 的 引导 示例 上 来 ， 并 且 对 它 的 类 型 形 参 ; 


的 例外 是 相等 和 恒 等 比较 (==，===，! =，! ==) 被 允许 。 


添加 一 个 约束 而 做 出 一 些 改变 。 这 个 约束 将 限制 类 型 形 参 允 许 是 什么 值 。 语 法 就 是 添加 一 个 关键 词 “as” 以 及 一 个 类 型 标注 在 类 型 形 参 列表 的 六 
添加 一 个 约束 : 


这 就 意味 着 ， 当 一 个 值 的 类 型 是 个 类 型 形 参 时 ， 你 不 能 对 它 能 做 很 多 事情 ， 你 不 能 调用 它 ， 不 能 在 它 上 调 
在 它 上 面 做 算术 运算 ， 或 者 其 他 诸如 此 类 的 事情 。 但 一 个 


只 别 符 后 面 。 让 我 们 回 到 那个 


class Wrapper<Tval as num> { 
private Tval $value; 


public function _ construct(Tval $value) { 


$this->value = $value; 


} 


public function setValue (Tval $value): 
$this->value = $value; 
} 


void { 


public function getValue(): 
return S$this->value; 
} 


Tval { 


在 这 里 ， 对 于 一 个 和 num 兼 容 的 类 型 值 ， 任 何 能 够 使 用 这 


个 类 的 代码 都 能 够 这 样 做 : 


function f(int $int, float $float, num $num, 


int $nullint, string $string, mixed $mixed): 
S$w = new Wrapper ($int); // OK 
$w = new Wrapper ($float); // OK 
$w = new Wrapper ($num); // OK 
Sw = new Wrapper ($nullint); // 错误 
Sw = new Wrapper ($string); ”// 错误 
$w = new Wrapper ($mixed); // 错误 


void { 


这 就 意味 着 ， 在 Wrapper 定 义 内 部 ， 对 于 “类 型 为 Tval 的 值 可 以 进行 


的 操作 和 对 于 类 型 为 num 的 值 可 以 进行 的 操作 ”是 一 样 的 。 所 以 ,我们 可 以 添加 这 样 一 个 方法 : 


class Wrapper<Tval as num> { 
private Tval $value; 
public function add(Tval $addend) : 
// Sthis->value 是 
$this->value += Bodden 
} 


void 


个 已 知 的 num 类 型 ， 及 史 疝 以 在 上 面 使 用 += 操 作 符 


// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


} 


可 以 使 


任何 合法 的 类 型 标注 作为 约束 。 最 常见 的 情况 就 是 使 


一 个 类 或 者 接口 的 名 字 作为 约束 。 这 样 做 的 话 ， 你 将 可 以 调 


在 类 或 者 接口 中 声明 好 的 方法 : 


interface HasID { 
Public function getID() : 
} 


int; 


function write to database<Tval as HasID> (Tval $value): 
$id = $value->getID(); 


void { 


// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


4 


每 个 类 型 形 参 至 多 有 一 个 约束 。 如 果 你 希望 限制 一 个 类 型 形 参 为 某 个 


使 用 这 个 新 的 接口 。 


单独 的 类 ， 而 这 个 


类 又 实现 了 多 个 特定 的 接口 ， 你 可 以 通过 对 它们 进行 扩展 ， 创 建 一 个 


合并 所 有 上 述 接口 的 新 接口 ， 然 后 在 约束 中 


interface HasID { 
public function getID() : 
} 


int; 


interface HasHashCode { 
public function getHashCode(): string; 
} 


interface HasIDAndHashCode extends HasID, HasHashCode { 
} 


function write to cache<Tval as HasIDAndHashCode> (Tval $value): void { 
$id = $value->getID(); 
$hash code = $value->getHashCode(); 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


这 里 并 没有 办 法 表述 像 Tval 那 样 必须 实现 这 个 接口 或 者 那个 接口 的 约束 。 


正如 我 们 所 看 到 的 一 样 ， 约 束 的 类 型 可 以 是 任何 合法 的 类 型 标注 。 这 包括 其 他 的 类 型 形 参 ， 甚 至 在 同一 个 形 参 列表 中 靠 前 的 类 型 形 参 。 例 如 ， 下 面 约束 的 使 用 方式 是 合法 的 : 


class GenericClass<Tclass> { 
Public function genericMethod<Tmethod as Tclass>(): Tmethod { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


} 
function lookup<Tvalue, Tdefault as Tvalue>(string $key, 


?Tdefault S$default = null): Tvalue { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


2.5” 重 温 未 决 的 类 型 


在 引导 范例 中 ,我 们 看 到 了 当 你 使 用 类 型 检查 器 的 时 候 ， 它 们 能 够 推断 泛 型 类 的 类 型 实 参 。 这 里 ， 类 型 检查 器 知晓 ， 对 于 类 型 形 参 Tval，Wrapper 已 经 用 int 类 型 蔡 代 进行 实例 化 了 。 


Sw = new Wrapper (20); 


这 个 推断 算法 的 准确 细节 已 经 超出 了 这 里 的 讨论 范围 ， 但 是 这 里 仍然 有 一 些 需要 知晓 的 结论 。 


类 型 检查 器 应 该 接受 下 面 的 代码 吗 ? 


function takes wrapper of int (Wrapper<int> $w): void { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


function main (int $n): void { 
Swrapper = new Wrapper ($n); 
takes_ wrapper of int ($wrapper); 


} 


直觉 上 来 说 ， 它 应 该 是 被 接受 的 ， 事 实 也 是 这 样 。 类 型 检查 器 知道 在 main () 函数 的 最 后 一 行 ， 变 量 $wrapper 是 一 个 整 型 的 wrapper， 所 以 允许 这 个 调 


那么 ， 换 成 下 面 的 代码 呢 ? 


function main (String $str): void { 
Swrapper = new Wrapper ($str); 
takes wrapper of int ($wrapper); 


} 


看 起 来 这 应 该 不 允许 执行 ， 


有 实 也 确实 如 此 。 


那么 ， 如 果 我 们 再 换 成 如 下 的 代码 呢 ? 


function main(int $n, string $str): void { 
Sw = new Wrapper ($n); 
$w->setValue ($str); 

} 


正如 我 们 在 第 一 个 例子 中 看 到 的 一 样 ， 类 型 检查 器 似乎 明白 $wrapper 在 第 一 行 后 面 是 个 Wrapper<int>。 所 以 看 起 来 类 型 检查 器 应 该 报告 一 个 错误 : 在 Wrapper<int > 上， 你 不 应 该 对 setValue () 传 


递 一 个 字符 串 作为 实 参 。 但 是 事实 上 ， 这 段 代 码 是 合法 的 。 


这 就 是 类 型 检查 器 使 用 未 决 的 类 型 的 另外 一 个 地 方 。 我 们 首次 接触 到 它们 在 1.6.2 节 ， 在 那里 ， 它 们 被 “类 型 检查 器 用 来 跟踪 一 个 变量 ” 


， 这 个 变量 能 够 在 一 个 程序 中 的 单一 点 拥有 不 同 的 类 型 ， 而 这 决 


定 于 达到 这 个 “点 ”代码 的 逻辑 路 径 。 而 对 于 泛 型 ， 类 型 检查 器 使 用 未 决 的 类 型 来 记 住 那些 还 没有 被 明确 规定 的 类 型 ， 当 类 型 检查 器 看 到 更 多 的 代码 后 ， 这 里 将 随时 保持 对 它们 进行 调整 的 自由 。 


在 第 一 行 的 后 面 ， 类 型 检查 器 已 经 非常 肯定 变量 yw 是 个 Wrapper， 但 是 关于 它 的 类 型 实 参 是 什么 ， 这 里 还 没有 明确 的 指引 。 它 想起 以 前 曾经 看 到 这 个 对 象 被 当 作 类 型 Wrapper<int> 进 行使 用 ， 但 是 int 


的 类 型 实 参 是 个 未 决 的 类 型 。 于 是 ， 它 继续 向 上 查看 相关 调用 $w->setValue ("a string ) ， 类 型 检查 器 查看 变量 yw 的 类 型 ， 来 看 这 个 调 有 


是 否 合法 。 当 它 看 到 未 决 的 类 型 实 参 时 ， 它 将 把 字符 串 添加 到 未 


决 的 类 型 中 去 ， 而 不 是 抛 出 一 个 错误 。 到 此 为 止 ， 就 类 型 检查 器 来 阅 ， 变 量 $w 或 者 是 Wrapper<int> 或 者 是 Wrapper<string>。 


而 对 于 读者 来 说 ， 直 觉 上 并 不 是 这 样 的 : 很 明显 在 $w 内 有 个 字符 串 。 但 是 类 型 检查 器 不 知道 Wrapper 的 语义 : 它 并 不 明白 Wrapper 只 包含 单个 值 。 类 型 检查 器 所 知晓 的 就 是 yw 好 像 被 当成 


Wrapper<int> 进 行使 用 ， 还 好 像 是 个 Wrapper<string>。 


当 检 查 到 一 个 未 决 的 类 型 实 参 违 反 某 个 类 型 标注 的 时 候 ， 它 将 变 成 一 个 “已 决 的 类 型 ”。 这 个 例子 将 展示 一 切 相 关 的 内 容 : 


function takes wrapper of int (Wrapper<int> $w): void { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 


function main(): void { 
Sw = new Wrapper (20); 
takes wrapper of int (S$w); 
$w->setValue (Ta string');??// 错误 ! 


} 


这 次 ， 类 型 检查 器 将 在 最 后 一 行 报告 一 个 错误 。 当 变量 $w 被 传递 给 函数 takes_wrapper_of_int () 时 ， 检 查 到 它 违 反 了 函数 的 形 参 类 型 标注 。 在 这 点 上 ， 变 量 $w 的 类 型 是 “已 决 的 ”。 类 型 检查 器 已 
经 看 到 变量 $w 应 该 是 一 个 Wrapper<int> 类 型 的 确凿 证 据 。 既 然 这 个 类 型 是 “已 决 的 ”了 ， 类 型 检查 器 在 对 setValue () 方法 的 调用 检查 上 也 就 不 会 宽大 处 理 了 。 在 一 个 已 决 的 类 型 Wrapper<int> 的 


Wrapper 实 例 上 调用 “setValue ("a string') ”是 非法 的 ， 所 以 类 型 检查 器 报告 了 一 个 错误 。 


2.6 ” 泛 型 和 亚 型 


让 我 们 回 到 关于 Wrapper 类 的 引导 范例 。 类 型 检查 器 应 该 接受 下 面 的 代码 吗 ? 


function takes wrapper of num(Wrapper<num> Sw) : void { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


function takes wrapper of int (Wrapper<int> $w): void { 
takes _ wrapper of num($w); 


} 


那么 问题 来 了 ， 传 递 一 个 整 型 的 wrapper 到 一 个 期 待 值 为 NWm 的 wrapper 的 话 ， 这 个 操作 是 非法 的 吗 ? 看 起 来 应 该 是 这 样 的 : int 是 num 的 亚 型 (意味 着 任何 为 int 的 值 都 会 是 个 num) ， 所 以 看 起 来 
Wrapper<int> 应 该 同样 是 Wrapper<num> 的 亚 型 。 


为 了 说 明 其 中 的 缘由 ， 我 们 请 思考 下 面 的 代码 ， 函 数 takes_ wrapper_ of _ num () 能 够 做 这 个 事情 : 


事实 上 ， 对 于 这 个 例子 ， 类 型 检查 器 将 会 报告 一 个 错误 。 对 于 类 型 检查 器 来 说 ， 我 们 关于 int 和 num 的 亚 型 关系 传递 给 Wrapper<int> 和 Wrapper<num> 之 间 亚 型 关系 的 假设 是 不 成 立 的 。 


function takes wrapper of num(Wrapper<num> $w): void { 


$w->setValue (3.14159) 7 


对 于 它 自己 来 说 ， 这 是 合法 的 : 设置 一 个 Wrapper<num> 内 部 的 值 为 一 个 float 类 型 的 值 。 但 是 如 果 你 传递 一 个 Wrapper<int> 到 上 述 版 本 的 函数 takes wrapper_ of num () 中 ， 这 将 会 导致 
wrapper 再 也 不 是 整 型 。 所 以 类 型 检查 器 不 接受 对 函数 takes wrapper_ of num () 传递 Wrapper<int>。 这 并 不 是 类 型 安全 的 。 需 要 特别 说 明 的 是 ， 这 里 有 一 项 铁 的 规则 : 类 型 检查 器 并 不 思考 函数 


takes wrapper of num ( 


) 实际 上 在 做 什么 。 即 使 函数 takes_wrapper_of_num () 是 空 的 ， 类 型 检查 器 仍然 会 报告 一 个 错误 。 


现在 ， 我 们 看 另外 一 段 代 码 ， 类 型 检查 器 应 该 接受 这 段 代 码 吗 ? 


function returns wrapper of int() : Wrapper<int> { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


function returns wrapper of num(): Wrapper<num> { 
return returns wrapper of int { 


} 


虽然 这 次 直觉 上 看 起 来 一 切 正常 ， 但 是 类 型 检查 器 会 再 一 次 报告 错误 。 原 因 是 非常 相似 的 。 设 想 一 下 ,我 们 在 空白 处 填 上 如 下 内 容 : 


function returns wrapper of int(): Wrapper<int> { 
static Sw = new Wrapper (20); 


return S$w; 


} 


function returns wrapper of num(): Wrapper<num> { 
return returns wrapper of int tz 


} 


function main(): void { 
S$wrapper_of num = returns wrapper of num(); 
S$wrapper_ of num->setValue (2.71828); 


} 


这 很 明显 是 非法 的 一 一 在 main () 函数 执行 后 ， 任 何 对 函数 returns wrapper_of int () 的 调用 都 会 返回 某 一 个 非 int 类 型 的 wrapper。 所 以 ， 再 一 次 ， 对 于 函数 returns wrapper_of num () 里 面 的 


return 语 句 ， 类 型 检查 器 会 报告 一 个 错误 。 


数组 和 集合 


数组 和 Hack 的 不 可 变 集合 类 (ImmyVector、ImmMap、Immset 和 Pair) 表现 上 是 不 一 致 的 。 举 例 来 说 ， 它 们 遵从 着 很 直观 的 概念 ，array<int> 是 array<num> 的 亚 型 。 下 例 中 对 数组 的 使 用 是 合法 


function takes array of numl(array<num> $arr): void { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


} 


function takes array of int (array<int> $arr): void { 
takes array of num($arr); ?22// OK 


} 


类 似 的 行为 对 于 不 可 变 集合 类 的 值 类 型 1 也 是 有 效 的 。 不 必 考虑 你 是 使 用 它们 自己 的 名 字 进行 注解 ， 还 是 用 类 似 ConstVector 这 样 的 接口 名 字 (这 是 推荐 的 ) 进行 注解: 


function takes constvector of num(ConstVector<num> $cv): void { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


function takes constvector of int (ConstVector<int> $cv): void { 
takes_constvector of num($cv);??// OK 


} 


function takes constmap of arraykey mixed(ConstMap<string, mixed> $cm): void { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


} 


function takes constmap of string int (ConstMap<string, int> $cm): void { 
takes constmap of arraykey mixed($cm);??// OK 


} 


为 什么 这 对 于 数组 和 不 可 变 集合 是 合法 的 ， 而 对 于 Wrapper 却 是 非法 的 ? 


就 不 可 变 集合 来 说 ， 原 


因 很 简单 : 它们 是 不 可 变 的 。 即 使 你 传递 一 个 ImmVector<int> 到 参数 为 ImmVector<nun> 的 函数 ， 这 个 函数 也 没有 办 法 设 


一 个 非 整 型 值 到 vector 中 。 这 里 没有 任何 方法 可 


以 破坏 vector 只 能 包含 整数 的 规矩 。 


就 数组 而 言 ， 道 理 也 是 一 样 的 。 出 于 相同 的 目的 ， 由 于 值 传递 语义 数组 和 不 可 变 集合 在 表象 上 几 了 


一 致 。 在 上 一 个 示例 中 ， 从 takes array_ of num () 的 视角 ， 在 函数 takes _array_of int () 主体 内 


的 数组 实际 上 是 只 读 的 。 函 数 takes_array_of num () 不 能 够 导致 数组 内 部 具有 非 整 型 值 。 


[由 因为 变 体 规则 ， 对 于 key 类 型 这 不 成 立 ( 详 见 2.7 节 内 容 


2.7” 进 阶 : 协 变 和 逆 变 


除非 你 正在 编写 一 些 很 常见 的 ， 类 似 集合 (collection) 的 代码 库 ， 否 则 你 可 能 并 不 需要 阅读 下 面 
本 小 节 的 内 容 是 关于 “ 当 你 必须 要 修改 相关 规则 的 时 候 将 如 何 做 ”。 


念 
念 ， 


关于 泛 型 的 亚 型 关系 是 如 何 被 它们 类 型 实 参 的 亚 型 关系 影响 的 概 
(我 们 使 用 int 和 num 作 为 类 型 实 参 的 示例 ) : 


“ 如果 Thing<int> 是 Thing<num> 的 亚 型 ， 我 们 说 Thing 对 于 T 是 协 变 的 〈covatiant) 。 数 组 在 它 所 有 


我 们 称 之 为 “ 变 体 (variance) ”。 这 里 三 种 不 同 的 变 体 。 设 想 一 下 ， 我 们 有 个 泛 


为 它 根本 就 无 法 访问 原始 数组 ， 只 有 复制 的 权限 。 


。key 的 类 型 形 参 出 现在 逆 变 位 ， 就 像 get0 函 数 的 形 参 一 样 ， 所 以 它 并 不 是 协 变 的 。 作 为 一 个 特例 ， 这 很 有 可 能 在 将 来 改变 。 


的 内 容 。 对 于 日 常 上 大 多 数 


例 来 说 ， 你 只 需要 知晓 我 们 正在 讨论 的 规则 是 存在 的 ， 并 且 知 道 为 什么 。 


型 类 叫做 Thing， 这 个 类 有 个 类 型 形 参 T。 然 后 


的 类 型 形 参 上 都 是 协 变 的 ， 不 可 变 集 合 类 在 它们 值 的 类 型 形 参 上 也 都 是 协 变 的 。 


“如果 Thing<num> 是 Thing<int> 的 亚 型 ， 我 们 说 Thing 在 T 上 是 北 变 的 《contravariant) 。 这 违反 直觉 , 但 这 也 是 可 能 的 ， 这 里 就 有 北 变 类 型 的 真实 程序 。 


“如果 上 面 两 项 都 不 为 真 ， 那么 我 们 说 Thing 在 T 上 是 不 变 的 。 


;五 : 
= 


有 


为 了 使 一 个 泛 型 在 它 的 类 型 形 参 上 是 协 变 ， 就 放置 一 个 加 号 在 类 型 形 参 之 前 。 请 仅 在 参数 列表 上 做 这 件 


情 。 在 定义 内 部 ， 还 和 以 前 一 样 使 


形 参 上 是 逆 变 的 ， 那 么 请 放置 一 个 减 号 在 类 型 形 参 之 前 。 如 下 所 示 : 


类 型 形 参 的 名 字 。 类 似 地 ， 如 果 想 使 一 个 泛 型 在 它 的 类 型 


class CovariantonT<+T> { 
private T $value;??// No + here 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompr: 


class ContravariantonT<-T> { 
private T $value;??// No - here 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompr 


Class InvariantOnT<T> { 
private T $value; 


essed/16125/0EBPS/Text/... 


essed/16125/0EBPS/Text/... 


// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


一 个 类 可 以 有 不 同 的 变量 类 型 形 参 : 


class DifferentVariances<Tinvariant, +Tcovariant, -Tcontravariant> { 


} 


// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


协 变 (Covariance) 


自 


a 词 的 前 级 “co-” 意 味 着 “协同 (with) ”， 对 了 


逆 变 (Conttravariance) 


自 


2.7.2 ”什么 时 候 使 用 它们 


对 于 你 写 下 的 大 多 数 类 来 说 ， 并 不 会 


到 协 变 或 者 逆 变 。 这 个 特性 仅 在 一 些 特殊 情况 下 有 作 


一 个 协 变 类 型 形 参 来 说 ， 泛 型 的 亚 型 关系 和 实 参 的 亚 型 关系 “在 同一 个 方向 上 ”变化 ， 


a 词 的 前 级 “contra-” 意 味 着 “对 抗 (against) ” ， 对 于 一 个 逆 变 类 型 的 形 参 来 说， 泛 型 的 亚 型 关系 和 实 参 的 亚 型 关系 相反 。 


因 


为 它们 沿 相同 的 方向 变化 ， 所 以 对 应 的 符号 是 个 加 号 。 


为 它们 沿 相反 的 方向 变化 ， 所 以 符号 是 个 


减 号 。 


: 协 变 主 要 用 于 只 读 类 型 。 比 如 ， 如 果 我 们 从 类 Wrappet 中 移 除 方法 setValue () ， 那 么 对 于 它 的 类 型 形 参 Tval 来 说 ， 它 就 是 只 读 的 。 也 就 是 说 ， 它 只 输出 类 型 Tval 的 值 ; 除了 在 构造 函数 中 ， 它 从 不 使 用 


它们 作 输 入 项 目 。 所 以 在 Tval 上 ，Wrappet 能 够 是 协 变 的 出。 


“ 北 变 是 用 来 只 写 类 型 的 


类 型 检查 器 通过 在 怎样 使 


首先 ， 我 们 介绍 简单 的 部 分 : 


“ public 和 protected 的 属性 类 型 仅 被 限制 为 不 可 变 类 型 形 参 。 


“ 返回 类 型 被 限制 为 不 可 变 或 者 协 变 的 类 型 形 参 。 它 们 是 


“ 除 构 造 函 数 外 ， 函 数 和 方法 的 形 参 类 型 被 限制 为 不 可 变 或 者 送 变 的 类 型 形 参 。 它 们 是 逆 变 位 置 。 


“ 私有 属性 类 型 和 构造 函数 形 参 类 型 没有 类 型 形 参 方面 的 限制 。 


然后 ， 我 们 说 明 稍 微 复杂 的 部 分 。 在 另外 一 个 逆 变 位 置 内 部 ， 还 可 以 有 另外 一 个 逆 变 位 置 。 而 内 部 逆 变 位 置 如 


协 变 和 逆 变 类 型 形 参 上 设置 限制 条 件 来 执行 它 。 明 确 地 说 ， 每 种 类 型 形 参 


。 举例 来 说 ， 一 个 序列 化 类 型 的 值 到 日 志文 件 的 泛 型 类 ， 对 于 类 型 的 值 可 能 是 只 写 的。 更 确切 地 说 ， 它 只 把 类 型 T 的 值 为 输入 ， 但 是 从 来 不 输出 它们 。 


参 只 允许 出 现在 代码 上 的 特定 位 置 ， 它 们 被 称 为 协 变 位 置 和 逆 变 位 置 。 


有 实 上 是 协 变 的 。 请 看 下 面 的 示例 : 


class WriteOnly<-T> { 
private T $value; 


public function _ construct(T $value) 
$this->value = Svalue; 


{ 


// 错误 ! 
Public function passToCallback( (function(T): void) $callback): void { 
$callback (Sthis->value) 7 
} 
} 


逆 变 类 型 形 参 T 出 现在 一 个 形 参 类 型 ($callback 的 类 型 ) 上 ， 而 后 一 个 参数 类 型 又 出 现在 了 另外 一 个 形 参 类 型 (passToCallback () 的 类 型 ) 的 内 部 。 这 就 是 在 一 个 逆 变 位 置 内 部 的 另外 一 个 逆 变 位 
置 。 所 以 它 是 协 变 的 。 因 此 它 是 非法 的 。 


你 可 以 具体 看 看 为 什么 会 是 这 样 ， 直 觉 上 ，passToCallback () 的 写法 将 导致 对 于 WriteOnly 外 部 的 内 容 ， 在 WriteOnly 实 例 之 外 出 现 得 到 类 型 T 值 的 可 能 性 。 


协 变 位 置 内 部 的 协 变 位 置 仍然 是 协 变 的 。 协 变 和 逆 变 的 工作 就 像 乘法 下 的 正 数 和 负数 ， 正 数 乘 以 正 数 得 到 正 数 ， 但 是 负数 乘 以 负数 得 到 的 也 是 正 数 。 
协 变 


让 我 们 在 类 Wrapper 中 移 除 方法 setValue () ， 然 后 把 类 型 形 参 设 置 为 协 变 的 : 


class Wrapper<+Tval> { 
Private Tval $value; 


public function _ construct(Tval $val) { 


$this->value = Sval; 
} 


Public function getValue(): Tval { 
return S$this->value; 
} 


协 变 类 型 形 参 Tval 以 如 下 情形 出 现 : 一 个 私有 属性 的 类 型 、 一 个 构造 函数 的 参数 、 一 个 返回 类 型 。 这 些 都 是 协 变 类 型 形 参 允 许 出 现 的 地 方 。 类 型 检查 器 将 会 接受 这 些 代码 而 不 会 报错 。 


接 下 来 的 代码 现在 也 是 被 接受 的 。 当 我 们 把 Wrapper<int> 按 照 Wrapper<num> 来 对 待 的 时 候 ， 放 置 在 协 变 类 型 形 参 上 的 限制 条 件 保证 了 这 里 没有 什么 途径 可 以 打破 类 型 安全 限制 。 


function takes wrapper of num(Wrapper<num> S$w): void { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


function takes wrapper of int (Wrapper<int> $w): void { 
takes wrapper of num($w); 


} 


如 果 你 试图 添加 一 个 改变 值 的 方法 ， 类 型 检查 器 将 会 报告 一 个 错误 : 一 个 协 变 类 型 形 参 出 现在 一 个 不 可 协 变 的 位 置 上 。 


class Wrapper<+Tval> { 
public function setValue (Tval $value): void {??// Error 
Sthis->value = $value; 


} 


// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


同样 的 道理 ， 如 果 你 改变 $value 属 性 的 访问 修饰 符 为 public 或 者 protected， 类 型 检查 器 也 会 报告 一 个 错误 : 一 个 非 私 有 的 属性 总 是 一 个 不 变 的 位 置 。 也 就 是 说 ， 你 不 能 在 这 里 使 用 协 变 或 者 逆 变 的 类 型 


逆 变 类 型 是 比较 少见 的 ， 这 是 因为 只 写 的 类 型 比 只 读 的 类 型 罕见 。 我 们 接 下 来 将 会 通过 一 个 类 来 加 深 对 逆 变 的 理解 。 在 这 个 类 中 ， 我 们 建立 了 一 个 值 的 buffer， 然 后 把 JSON 以 流 的 形式 写 入 其 中 。 


class JSONLogger<-Tval> { 
Private resource $stream; 
private array<Tval> $buffer = array(); 
public function _ construct (resource $stream) { 
$this->stream = $stream; 


" 


public function log(Tval $value): void { 
$buffer[] = $value; 
} 


public function flush(): void { 
fwrite ($this->stream, json encode($this->buffer)); 
$this->buffer = array(); 
} 


请 注意 ， 逆 变 类 型 形 参 Tval 只 出 现在 一 个 方法 的 参数 和 一 个 私有 属性 之 中 ， 所 以 类 型 检查 器 接受 了 这 段 代 码 。 如 果 你 试图 把 $buffer 设 置 为 public 或 者 protected， 或 者 为 这 个 类 添加 一 个 返回 类 型 为 
Tval 的 方法 ， 类 型 检查 器 都 会 报告 一 个 错误 。 


这 个 违反 直觉 的 逆 变 类 型 形 参 意味 着 JSONLogger<num> 是 JSONLogger<int> 的 一 个 亚 型 。 由 下 面 的 代码 来 进行 验证 : 


function wants to log ints (JSONLogger<int> $logger): void { 


$logger->10g (20); 


function wants to log nums (JSONLogger<num> $logger): void { 
wants_to log ints ($logger);?? // OK 
$logger->1l0g (3.14); 


这 里 的 代码 把 JSJONLogger<num> 传 递 给 了 一 个 期 待 参数 为 JSJONLogger<int> 的 函数 。 这 是 可 以 的 ， 因 为 JSJONLogger<num> 可 以 做 任何 JSONLogger<int> 可 以 做 的 事情 (甚至 更 多 ) 。 因 为 这 里 
在 JSONLogger 之 外 ， 没 有 任何 途径 可 以 获取 Tval 类 型 的 值 。 在 这 个 类 外 部 的 代码 也 不 能 从 它 获 取 其 不 期 待 的 类 型 的 值 。 


四 注意 Wrapper 可 以 具有 不 涉及 Tval 的 读 或 者 写 功能 ， 并 且 Tval 仍 然 能 够 是 协 变 的 。 重 要 的 是 Tval 的 只 读 属 性 ， 而 非 Wrapper 的 只 读 属 性 。 


第 3 章 “Hack 的 其 他 特性 


本 质 上 来 阅 ，Hack 有 四 种 主要 的 特性 使 之 区 别 于 PHP。 它 们 分 别 是 : 类 型 检查 、 集 合 、 异 步 函 数 和 XHP。 当 然 ， 除 了 上 述 这 些 ，Hack 还 有 大 量 的 小 特性 ， 被 设计 用 来 简化 某 些 常见 模式 或 者 解决 一 些 
小 的 问题 。 


3.1 枚 举 


一 个 枚 举 类 型 是 一 系列 有 关 常 量 的 集合 。 它 和 简单 地 创建 全 局 常量 或 者 类 常量 不 一 样 ， 创 建 一 个 枚 举 将 产生 一 个 新 的 类 型 : 你 可 以 在 类 型 标注 中 使 用 这 个 枚 举 的 名 字 。 同 时 它们 提供 一 些 功能 ， 比 如 无 
须 借 助 一 些 重量 级 的 反射 AP1， 就 可 以 得 到 一 个 包含 全 部 合法 名 称 (或 值 ) 的 数组 。 


枚 举 类 型 的 语法 是 : 关键 词 “enum” 后 跟随 着 这 个 枚 举 类 型 的 名 字 ， 然 后 是 冒号 ， 接 着 int 整 型 或 者 string 字 符 串 (string 是 枚 举 的 基础 类 型 ) ， 最 后 是 大 括号 括 起 来 的 ， 分 号 分 隔 的 枚 举 成 员 列表 。 每 
个 成 员 都 是 一 个 名 字 ， 随 后 是 一 个 等 号 和 一 个 值 (必须 和 枚 举 的 基础 类 型 匹配 ) 。 


enum CardSuit : int { 


SPADES = 0; 
HEARTS = 1; 
CLUBS = 2; 
DIAMONDS = 3; 


} 


枚 举 类 型 的 名 字 和 类 的 名 字 有 着 一 样 的 限制 条 件 (这 主要 得 益 于 它们 可 能 包含 的 特性 等 ) ， 当 一 个 类 和 一 个 枚 举 类 型 有 同样 的 名 字 时 ， 这 里 会 报告 一 个 错误 。 


枚 举 成 员 名 字 和 类 的 常量 名 字 有 着 一 样 的 限制 。 在 枚 举 类 型 内 部 ， 名 字 必 须 唯 一 。 如 果 这 里 有 两 个 同样 名 字 的 成 员 同时 存在 于 枚 举 类 型 内 部 ， 那 么 类 型 检查 器 将 会 报告 一 个 错误 ， 而 HHVM 将 会 显示 一 


个 致命 错误 。 


枚 举 成 员 的 值 必须 是 标量 的 ， 这 就 是 说 它们 必须 能 够 被 静态 地 评估 。 当 然 ， 对 于 类 的 常量 也 存在 着 同样 的 限制 条 件 。 这 些 值 本 身 在 枚 举 内 部 并 不 必 是 唯一 的 。 如 果 你 不 能 保证 值 唯一 的 话 ， 唯 一 可 能 会 
遇 到 的 问题 就 是 ， 当 你 在 枚 举 类 型 上 调用 函数 getNames () 的 时 候 (参见 “ 枚 举 相关 函数 ”的 内 容 ) ， 将 会 抽出 一 个 不 变量 异常 (InvariantException) 。 


你 可 以 使 用 与 访问 类 常量 类 似 的 语法 访问 枚 举 类 型 的 值 : 


function suit for card index(int $index): CardSuit { 
if ($index <13) { 
return CardSuit::SPADES; 
} else if ($index < 26) { 
return CardSuit: :HEARTS; 
else if ($index < 39) { 
return CardSuit::CLUBS; 
} else { 
return CardSuit: :DIAMONDS; 


} 
} 


枚 举 是 独特 的 类 型 。 例 如 ， 虽 然 CardSuit 的 基础 类 型 是 int， 但 是 你 不 能 像 对 待 CardSuit 类 型 一 样 对 待 一 个 int 类 型 ， 反 之 亦 然 。 


function takes int(int $x): void { 
function takes card suit (CardSuit $suit): void { 


function main() { 
takes int (CardSuit::SPADES); // 错误 
takes card suit (1); // 错误 
} 


如 果 想 把 一 个 枚 举 类 型 的 值 转化 为 它 的 基础 类 型 ， 只 需要 使 用 PHP 与 强制 转化 相关 的 表达 式 即 可 。 如 果 要 往 相反 的 方向 进行 转化 ， 则 需要 使 用 枚 举 类 型 的 assert () 或 者 coerce () 函数 ， 这 两 个 函数 
将 会 在 “ 枚 阿 举 相关 函数 ”中 进行 介绍 。 


如 果 你 想 显 式 地 转化 一 个 枚 举 类 型 到 它 的 基础 类 型 ， 那 么 你 只 需要 添加 关键 词 “as” ， 然 后 在 花 括号 开始 之 前 重复 一 下 相关 的 基础 类 型 : 


enum CardSuit : int as int { 


SPADES = 0; 
HEARTS = 1; 
CLUBS = 2; 
DIAMONDS = 3; 


} 


function takes int(int $x): void { 


function main(): void { 
takes int (CardSuit::HEARTS);// OK 
} 


使 用 枚 举 类 型 优越 于 使 用 类 常量 的 一 个 地 方 就 是 : 当 在 switch 语 句 中 使 用 枚 举 类 型 的 值 控制 表达 式 时 ， 类 型 检查 器 将 确保 所 有 的 可 能 性 都 被 顾及 。 如 果 有 一 些 分 支 情况 并 没有 在 你 的 代码 里 面 书写 ， 那 
么 类 型 检查 器 将 会 报告 一 个 错误 ， 告 诉 你 哪些 分 支 丢 失 了 : 


<?hh // strict 
enum CardSuit : int { 


SPADES = 0; 
HEARTS = 1; 
CLUBS = 2; 
DIAMONDS = 3; 


} 


function suit symbol (CardSuit $suit): string { 
switch ($suit) { 
Case CardSuit: :SPADES: 
return "\xe2\x99\xa4"; 
Case CardSuit: :CLUBS : 
return "\xe2\x99\xa7"; 
} 
} 


类 型 检查 器 将 会 报告 如 下 错误 : 


/home/oyamauchi/test.php:10:13,17: Switch statement nonexhaustive; the 
following cases are missing: HEARTS, DIAMONDS (Typing[4019]) 
/home/oyamauchi/test .php:2:6,13: Enum declared here 


可 以 通过 添加 一 个 default 标 签 来 消除 这 个 错误 。 这 样 的 话 ， 你 就 不 需要 显 式 处 理 所 有 的 枚 举 成 员 了 。 值 得 注意 的 是 ， 如 果 你 显 式 处 理 了 所 有 的 可 能 情况 ， 还 外 加 了 一 个 default 标 签 的 话 ， 那 么 类 型 检 
查 器 将 会 给 你 一 个 警告 内 容 ， 告 诉 你 default 是 多 余 的 。 


枚 举 相关 函数 


正如 我 们 所 看 到 的 那样 ， 枚 举 类 型 表现 得 更 像 是 个 伪 类 。 它 们 分 享 类 的 命名 空间 ， 并 且 它 们 的 成 员 都 以 同样 的 语法 进行 访问 。 这 里 还 有 更 多 的 相似 点 : 任何 枚 举 类 型 都 有 六 个 静态 方法 ， 这 些 方法 可 以 
被 用 来 获得 枚 举 成 员 的 信息 ， 还 可 以 用 来 转换 任意 值 到 枚 举 类 型 。 


例如 ， 如 果 你 传递 一 个 int 整 型 ， 并 且 想 要 把 它 作 为 一 个 CardSuit 来 使 用 ， 你 可 以 这 样 做 : 


function takes card suit(CardSuit $suit) { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


function legacy function(int S$suit) { 
$enum suit = CardSuit: :coerce ($suit); 
if ($enum suit !== null) { 
takes card suit ($enum suit); 
4 
i 


这 里 是 相关 的 所 有 方法 。 我 们 假设 返回 的 枚 举 类 型 的 名 字 为 ExampleEnum : 


' assett (mixed$value) : ExampleEnum， 将 会 返回 一 个 转化 为 枚 举 类 型 的 $value， 前 提 是 这 个 gvalue 对 应 枚 举 类 型 的 基础 类 型 ， 并 且 它 是 这 个 对 应 枚 举 类 型 的 成 员 。 如 果 不 能 满足 这 两 个 条 件 的 话 ， 它 将 


会 抛 出 一 个 “ 非 期 待 值 (Unexpected ValueException) ”的 异常 。 


“assertAll (Traversable<mixed>$value) : Container<ExambleEnum> ， 该 函数 将 会 对 给 定 的 可 遍历 的 参数 〈 见 5.4.1 节 的 内 容 ) 中 的 每 个 值 调 用 函数 assert () 。 然 后 将 返回 一 个 包含 所 有 正确 类 型 值 的 容器 


Container。 如 果 这 些 值 中 的 任何 一 个 不 是 枚 举 成 员 ， 这 里 将 会 抛 出 一 个 “ 非 期 待 值 ”异常 。 
“ coerce (mixed$value) : ? ExampleEnum， 此 方法 和 assett () 非常 相似 ， 但 是 对 于 $value 不 是 枚 举 成 员 变量 的 情况 ， 将 会 返回 null， 而 不 是 抛 出 一 个 异常 。 


. getNames () : array<ExampleEnum，string> ， 将 会 返回 一 个 数组 映射 (mapping) ， 这 个 映射 关系 是 从 枚 举 成 员 的 值 到 它们 的 名 字 。 如 果 这 些 值 在 枚 举 类 型 内 部 不 是 唯一 的 ， 那 么 将 会 抛 出 一 个 “不 变 


bi 
EE 


常 (InvariantException) 。 
“ getValues () : array<string，ExampleEnum>， 将 会 返回 一 个 从 枚 举 成 员 的 名 字 到 它们 值 的 数组 映射 。 


“isValid (mixed$value) : bool， 返 回 一 个 布尔 型 ， 用 于 判断 $value 是 否 为 对 应 枚 举 类 型 的 成 员 。 


类 型 别名 是 对 于 已 经 存在 的 类 型 赋予 新 的 名 字 的 方法 。 这 里 有 两 种 类 型 别名 的 情况 : 透明 的 (transparent) 和 非 透明 的 opaque) 。 这 对 应 于 你 可 能 会 对 一 个 类 型 进行 重 命名 的 两 种 原因 。 


3.2.1 ”透明 类 型 别名 


如 果 你 经 常 使 用 一 个 很 复杂 的 类 型 ， 你 可 以 给 它 起 一 个 简单 的 别名 ， 这 样 的 话 ， 一 来 你 可 以 降低 视觉 上 的 复杂 度 ， 二 来 还 可 以 少 输入 几 个 字符 ， 还 能 更 清晰 地 表达 它 的 含义 。 


例如 : 如 果 你 使 用 类 型 Map<int，Vector<int> > ， 那 么 你 可 以 给 它 设置 一 个 别名 为 UserIDToFriendIDsMap， 逻 辑 上 可 能 会 更 加 清晰 。 这 个 就 是 “透明 别名 ”的 主要 使 用 场景 。 


这 个 语法 非常 简单 ， 主 要 由 下 面 几 部 分 组 成 : 关键 词 type、 为 这 个 类 型 设置 的 新 名 字 、 一 个 等 号 ， 还 有 你 正在 重 命名 的 类 型 (这 也 叫做 基础 类 型 ) ， 请 参见 下 例 : 


type UserIDToFriendIDsMap = Map<int, Vector<int>>; 


这 个 类 型 别名 的 声明 语句 必须 放置 在 一 个 文件 的 顶层 ， 而 不 是 放置 在 其 他 语句 的 内 部 。 等 号 右边 的 类 型 可 以 是 任何 合法 的 类 型 标注 。 一 旦 这 个 类 型 别名 被 定义 好 ， 这 个 新 的 名 字 就 可 以 被 用 作 类 型 标注 
了 。 类 型 别名 和 类 分 享 同一 个 命名 空间 ， 所 以 如 果 一 个 类 型 别名 和 一 个 类 具有 相同 的 名 字 ， 将 会 是 个 错误 。 


透明 类 型 别名 可 以 显 式 地 转化 为 它 的 基础 类 型 ， 反 之 亦 然 : 


type transparent = int; 


function make transparent (int $x): transparent 
return $x;/7 OK: int Ee 品 式 转化 
} 


function takes int(int $x): void { 
function main(): void { 
七 = make transparent (10); 


takes_int($t);// OK: transparent 类 型 到 int 类 型 的 显 式 转化 
} 


3.2.2 ” 非 透 明 类 型 别名 


创建 一 个 类 型 别名 的 另外 一 个 原因 就 是 : 你 为 了 一 个 特殊 意义 正在 使 用 一 个 原始 的 类 型 。 一 个 常见 的 例子 就 是 使 用 整 型 作为 用 户 的 ID。 你 可 以 设置 一 个 类 型 别名 叫做 userid， 这 样 就 可 以 把 用 于 用 户 ID 
的 整 型 和 其 他 的 整 型 有 效 地 进行 区 分 。 当 一 个 整数 被 用 作用 户 ID 的 时 候 ， 类 型 别名 就 可 以 帮助 避免 由 于 整 型 代表 其 他 一 些 信息 (例如 一 个 账户 或 者 时 间 戳 ) 可 能 带 来 的 错误 。 


另外 一 个 类 型 别名 的 例子 是 有 关 字 符 串 类 型 的 。 你 可 以 对 字符 串 类 型 定义 一 个 叫做 sqlstring， 并 且 在 你 的 SQL 数据 库 的 接口 中 使 用 它 ， 这 可 以 避免 意外 地 使 用 一 个 可 能 没有 被 合理 转 义 过 的 查询 字符 串 
(另外 一 个 关于 这 种 区 别 的 例子 参见 7.1.2 节 的 相关 内 容 ) 。 


非 透明 别名 就 出 于 这 样 的 目的 而 使 用 。 透 明和 非 透明 别名 的 区 别 就 是 : 除非 在 这 个 别名 被 定义 的 文件 中 ， 一 个 非 透明 别名 不 能 够 被 转化 成 它 的 基础 类 型 (反之 亦 然 ) 。 


除了 关键 词 type 被 蔡 换 成 newtype 外 ， 非 透明 别名 和 透明 别名 的 语法 是 一 样 的 : 


newtype userid = int; 


这 里 应 用 一 样 的 限制 : 类 型 别名 不 能 够 和 一 个 类 具有 相同 的 名 字 ， 并 且 相关 的 声明 必须 放置 一 个 文件 的 顶层 之 中 。 


为 了 论证 如 何 使 


newtype opaque = int; 


function make opaque (int $x): opaque { 
return $x; 


} 


值得 注意 的 是 ， 本 文件 中 的 代码 允许 显 式 地 转化 


这 是 允许 的 。 


在 另外 一 个 文件 中 ， 我 们 试图 这 样 使 


KC} 


function takes int(int $x): void { 


function takes opaque (opaque $x): void { 


function main(): void { 
takes_ int (make opaque (10)); // 错误 
takes_opaque (20); // 错 误 


} 


一 个 非 透 明 别 名 ， 可 以 设想 我 们 拥有 一 个 文件 ， 在 这 个 文件 中 定义 了 相关 的 别名 ， 还 有 一 个 相关 的 转换 函数 : 


正如 这 个 例子 中 所 显示 的 那样 ， 如 果 你 想 使 一 个 非 透明 别名 在 它 的 文件 之 外 也 有 用 ， 你 必须 在 同一 个 文件 中 ， 定 义 一 些 方法 


没有 任何 办 法 在 它们 之 间 进 行 转换 ， 也 没有 办 法 创建 别名 类 型 的 值 。 


基础 类 型 到 对 应 的 别名 类 型 ， 从 函数 定义 上 ， 该 函数 的 返回 类 型 为 opaque， 但 是 实际 上 从 该 函数 中 返回 了 一 个 类 型 为 int 的 值 。 对 于 类 型 检查 器 来 说 ， 


于 别名 类 型 和 基础 类 型 之 间 的 相互 转换 。 否 则 ， 对 于 其 他 文件 中 的 代码 ， 


就 像 设置 int 的 别名 为 userid 一 样 ， 既 然 非 透 明 别 名 意味 着 被 用 作 具 有 语义 的 别名 ， 那 么 强制 使 用 显 式 的 转换 函数 就 是 一 个 特性 了 ， 这 将 避免 意外 地 把 普通 的 整 型 用 作 一 个 用 户 ID。 相 关 的 转换 函数 也 同 
样 是 进行 检验 操作 的 好 地 方 : 例如 ， 你 可 以 通过 确认 它 不 是 负数 来 检测 传递 进入 的 整数 是 个 狐 似 合理 的 用 户 ID。 


把 你 的 用 


户 ID 值 调 高 


如 果 你 正在 从 零 开 始 新 的 Web 应 用 编程 〈 换 名 话说 ， 使 用 一 个 空 的 数据 库 ) ， 这 里 将 有 个 你 可 以 做 的 非常 简单 的 事情 ， 对 于 这 款 应 用 接 下 来 的 生命 周期 来 说 ， 这 将 立刻 消除 潜在 的 一 整 类 的 bug。 如 果 你 
在 数据 库 表 中 使 用 了 一 个 自 增 列 来 分 配 用 户 的 ID (这 非常 经 典 、 合 理 ) ， 在 其 中 插入 任何 行 之 前 ， 请 设置 你 的 自 增 值 到 一 个 天 文 数字 。 关 于 “天 文 数字 ”， 我 意思 是 248 或 者 临近 的 数值 (你 可 以 用 代码 
1<<48 来 表示 ) 。 


这 样 的 话 ， 在 你 的 代码 中 ， 将 不 会 有 哪些 “ 非 用 户 ID” 的 整数 和 “用 户 ID” 很 相似 了 。 在 PHP 和 Hack 中 ， 数 组 下 标 、 数 组 计数 、 字 符 串 长 度 都 不 可 能 那么 高 。Unix 时 间 蕉 也 不 太 可 能 那么 高 ， 除 非 你 正 
在 处 理 未 来 890 万 年 的 时 间 戳 。 当 然 这 里 也 不 必 担 心 浪费 太 多 的 ID 空间 ， 从 248 开 始 的 话 ， 这 仍然 有 900 亿 亿 的 ID 可 以 使 用 。 


做 完 这 些 之 后 ， 你 就 可 以 用 “newtype usetid=int” 正 式 定义 一 个 非 透明 变量 别名 了 。 在 对 用 户 ID 相关 的 转换 函数 进行 验证 的 时 候 ， 只 需要 验证 相关 值 是 否 大 于 248 即 可 ， 如 果 为 真 ， 那 么 就 几乎 可 以 确认 


这 是 个 合 


法 的 用 户 ID。 


一 个 非 透 明 别 名 可 以 拥有 一 个 附加 的 约束 类 型 ， 这 个 约束 将 允许 该 别名 被 定义 的 文件 之 外 的 代码 ， 显 式 地 转化 该 别名 类 型 到 它 的 约束 类 型 ， 但 反之 不 成 立 。 通 常 来 说 ， 这 个 约束 类 型 和 它 的 基础 类 型 一 


这 个 语法 就 是 在 类 型 别名 和 等 号 之 间 ， 添 加 一 个 关键 词 as 和 一 个 类 型 标注 (就 是 对 应 的 约束 类 型 ) 。 


例如 


， 在 一 个 文件 中 我 们 这 样 定义 别名 : 


newtype totally opaque = int; 
newtype with constraint as int = int; 


function make totally opaque (int $x): totally opaque { 
return $x; 


function make with constraint (int $x) : 


return $x; 


} 


with constraint { 


在 另外 一 个 文件 中 ， 我 们 试 


使 用 它们 : 


[ 


function takes int(int $x): void { 


function takes totally opaque (totally opaque $x): void { 


} 


function takes with constraint (with constraint $x): void { 


function main(): void { 


takes_ int (make totally opaque (20)); // 错误 
takes int (make with constraint (20)); // OK 
takes totally_ opaque (20); ”// 错误 

takes with constraint (20); ”// 错误 


这 个 特性 是 非常 有 用 的 ， 它 可 以 使 老 代码 和 使 


型 。 为 了 使 事情 更 为 简单 ， 你 可 以 对 该 类 型 别名 添加 


3.23 


类 型 别名 可 以 在 HHVM 加 强 版 的 


自动 加 载 类 型 别名 


3.3 数组 形状 


动 加 载 系统 中 被 自动 加 载 ， 详 情 可 以 参见 3.7 节 的 相关 内 容 。 


非 透明 别名 的 新 代码 之 间 建 立 沟通 的 桥梁 。 你 可 以 使 用 int 基 础 类 型 建立 一 个 非 透明 别名 userid， 但 是 可 能 在 老 的 代码 中 ， 仍 然 需要 传递 用 户 1D 为 整数 
0 一 个 约束 ， 这 样 就 可 以 无 颖 地 传递 userid 类 型 的 值 到 期 待 int 参 数 的 相关 函数 中 了 。 


在 PHP 代 码 库 中 ， 使 用 一 个 数组 作为 伪 对 象 的 做 法 非常 常见 。 例 如 在 代码 中 ， 我 们 并 没有 定义 一 个 有 着 用 户 ID 和 名 称 作为 属性 的 User 类 ， 反 而 仪 仅 简单 地 传递 一 个 有 着 id 和 名 称 作 为 key 的 数组 来 代表 
ja 


数组 形状 (array shape) 就 是 用 来 告知 类 型 检查 器 ， 关 于 类 似 此 情况 中 数组 结构 的 一 种 途径 。 类 型 检查 器 能 够 对 数组 进行 验证 ， 以 便 检查 对 应 数组 是 不 是 具有 一 组 正确 的 key 值 ， 以 及 对 应 的 key 是 不 
是 指向 了 正确 类 型 的 value。 


数组 形状 的 定义 语法 是 关键 词 shape， 接 着 是 一 组 圆 括号 包 误 的， 逗号 分 隔 的 键 值 对 。 每 个 键 值 对 都 是 这 样 的 : 一 个 key (或 者 是 一 个 字符 串 字面 量 ， 或 者 是 一 个 值 为 整 型 或 者 字符 类 型 的 类 常量 ) ， 随 
后 是 token 串 => ， 然 后 就 是 就 是 一 个 类 型 标注 。 而 对 于 一 个 shape 表 达 式 ， 唯 一 合法 出 现 的 位 置 就 是 类 型 别名 的 右手 边 〈 详 见 前 文 相关 内 容 ) : 


type user = shape('id' => int, "name' => String) 


一 个 shape 事 实 上 就 是 一 个 有 着 类 型 检查 器 需要 的 特殊 追踪 作用 的 数组 。 而 创建 一 个 shape 的 语法 ， 和 创建 数组 的 语法 array () 是 一 样 的 ， 但 是 我 们 需要 把 使 用 关键 词 shape 来 蔡 代 array: 


function make user shape (int $id, string Sname) : user { 
return shape('id' => $id, 'name' => $name); 


} 
// 这 也 能 正常 工作 


function make user shapel(int $id, string $name): user { 
$user = shape(); 
$user['id'] = $id; 
$user['name'] = $name; 
return $user; 


我 们 可 以 获得 一 个 key 和 value 类 型 被 追踪 的 数组 。 如 果 你 传递 一 个 shape 到 is_array() 函数 ， 那 么 将 返回 真 。 


、 主 ak 


值得 注意 的 是 ， 在 该 函数 第 二 个 版 本 的 函数 体内 ， 直 到 第 三 行 代码 ， 变 量 $user 的 值 才 符合 user 的 shape 声 明 。 这 并 不 是 一 个 问题 ， 变 量 检查 器 只 在 它 检测 到 和 类 型 标注 相 违背 时 才 会 加 强 和 shape 声 明 
的 一 致 性 。 对 应 到 本 例 中 ， 就 是 在 return 语 句 的 这 个 点 上 。 


在 user 这 个 范例 中 ， 两 个 字段 都 是 必 填 项 ， 当 检查 是 否 与 标注 相 违背 时 ， 它 们 中 的 任何 一 项 在 shape 中 缺失 ， 类 型 检查 器 都 会 报告 一 个 错误 : 


<?hh 
type user = shape('id' => int, ‘'name' => String) 


function make user shape (int $id, string $name): user { 
$user = shape(); 
$user['id'] = $id; 
return $user; 


} 


类 型 检查 器 将 会 报告 如 下 错误 : 


/home/oyamauchi/test.php:7:10,14: Invalid return type (Typing[4057]) 
/home/oyamauchi/test .php:6:3,19: The field 'name' is missing 
/home/oyamauchi/test .php:4:24,27: The field 'name' is defined 


目前 为 止 ， 还 没有 办 法 设置 一 个 字段 为 可 选 。 最 接近 的 一 个 可 选 办 法 就 是 设置 该 字段 的 类 型 为 nullable。 这 样 的 话 ， 类 型 检查 器 对 shape 进 行 检 查 的 时 候 ， 如 果 发 现 某 个 字段 缺失 ， 并 不 会 抱怨 什么 ,但 
是 在 运行 环境 中 ， 上 述 代 码 可 能 会 引发 一 个 “E_NOTICE” 级 别 的 错误 (未 定义 的 索引 ) 。 最 好 的 办 法 就 是 设置 该 字段 类 型 为 nullable， 而 且 当 这 里 确实 没有 什么 值 要 存储 的 时 候 ， 请 显 式 地 设置 该 字段 为 


null。 


当 对 shape 的 字段 进行 读 取 时 ， 如 果 你 试图 读 取 一 个 在 shape 的 声明 中 不 存在 的 字段 ， 类 型 检查 器 将 会 报告 一 个 错误 。 接 下 来 的 例子 将 假设 user 的 定义 和 早期 一 样 。 


function log user data(user $user): void { 
$id = $user['id']; 
Sname = $user['name']; 
$is admin = $user['is admin'];  // 错误 : 字段 'is_admin' 丢 失 
printf ("%d (%s) (%d)", $id, $name, $is admin); 


当 一 个 shape 被 检查 是 否 符合 其 声明 的 时 候 ， 如 果 它 有 任何 不 属于 其 定义 的 key， 将 会 导致 失败 : 


$user = shape () 7 

S$user['id'] = 123; 

$user['name'] = 'Your Benefactor'; 

$user['is admin'] = true; 

log user data ($user); // 错误 : 字段 'is_admin' 被 定义 了 


如 果 你 在 shape 上 使 用 hh_client--type-at-pos 的 话 ， 那 么 它 将 仅仅 显示 [shapel]。 这 里 要 重申 一 下 : 一 个 shape 就 是 一 个 数组 ， 只 不 过 数组 的 key 被 类 型 检查 器 追踪 。 执 行 不 会 结束 ， 直 到 一 个 shape 必 
须 通过 一 个 类 型 标注 (例如 当 它 被 传递 给 一 个 函数 、 从 一 个 函数 中 返回 ， 或 者 被 分 配给 一 个 属性 时 ) 。 


为 了 更 容易 地 追踪 shape， 类 型 检查 器 对 你 能 够 做 的 事情 做 了 些 限制 : 


“ 你 不 能 够 对 未 知 的 Key 进行 读 写 ， 像 echo$shape[$key] 或 者 $shape[$key]=10， 即 使 $key 是 静态 的 。 方 括号 内 部 的 表达 式 必须 是 个 字符 串 字 面 量 ， 或 者 是 个 类 常量 (常量 对 应 的 值 是 整 型 或 者 字符 串 ) 。 同 样 
的 限制 在 shape 声 明 中 的 key 上 已 经 存在 。 


“ 你 不 能 使 用 附加 操作 符 ， 例 如 “$shape[]=10”。 


“ Shape 不 实现 接口 Traversable 或 者 Container (具体 参见 5.4.1 节 的 相关 内 容 ) 。 这 就 是 说 ， 你 不 能 使 用 foreach 对 shape 进 行 遍历 。 


3.4” 拉 姆 达 表达 式 


需 恋 量 | 


拉 姆 达 表 达 式 提供 了 一 个 对 PHP 闭 包 语法 的 简写 形式 ， 在 PHP 闭 包 语法 中 ， 不 足 的 地 方 就 是 : 你 必须 对 应 捕获 的 闭 包 范 围 内 的 所 有 变量 都 进行 命名 。 拉 姆 达 表 达 式 则 可 以 创建 自动 捕获 所 有 必需 变量 的 
闭 包 。 


例如 ， 设 想 我 们 有 一 个 用 户 ID 的 数组 ， 然 后 我 们 希望 使 用 array_ map () 函数 来 查找 每 个 ID 对 应 的 用 户 对 象 。 


$id to user map = /* http://www.hzcourse.com/resource/readBook?path=/openresources/teach te rt i uy 
$user ids = /* http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... */ 
$users = array map( 

$user ids, 

function ($id) use ($id to user map) { return $id to user map[$id]; } 


8 


我 们 可 以 把 最 后 一 行 的 闭 包 重 写 为 一 个 拉 姆 达 表 达 式 。 例 如 : 


$users = array map ($user ids, $id 一 > $id to user map[$id]); 


得 注意 的 是 ， 这 里 并 没有 使 用 关键 词 function， 也 没有 使 用 列表 、 关 键 词 return 和 大 括号 。 变 量 $id_to_user_map 是 在 闭 包 范 围 内 自动 被 捕获 的 ， 并 不 需要 显 式 地 识别 它 。 所 有 变量 都 是 通过 value 捕 
获 的， 而 不 能 使 用 拉 姆 达 表 达 式 通过 一 个 引用 来 进行 捕获 。 


这 个 语法 主要 基于 新 的 操作 符 ==>。 它 的 左边 对 应 的 是 闭 包 的 实 参 列 表 。 如 果 这 里 仅 有 实 参 而 没有 类 型 标注 ， 那 么 所 有 你 需要 的 就 是 一 个 变量 名 称 ， 就 像 上 述 范例 展示 的 那样 。 如 果 你 一 个 实 参 也 没 
有 、 多 于 一 个 实 参 、 任 何 带 类 型 标注 的 实 参 ， 或 者 有 个 返回 的 类 型 标注 ， 你 都 必须 在 实 参 列表 周围 放置 圆 括号 。 下 面 的 例子 中 ， 有 两 个 类 型 标注 的 实 参 ， 还 有 一 个 返回 类 型 标注 : 


usort( 

$players, 

(Player S$one, Player $two): int ==> $one->getScore() - Stwo->getScore () 
); 


对 于 操作 符 ==> 的 右 侧 ， 你 可 以 用 两 样 东西 ， 或 者 是 个 表达 式 ， 或 者 是 个 大 括号 括 起 来 的 语句 列表 。 如 果 仅 仅 是 个 表达 式 ， 表 达 式 的 值 就 是 闭 包 的 返回 值 ， 如 本 例 中 演示 的 。 如 果 是 个 语句 列表 ， 那 么 
你 就 可 以 使 用 一 个 常见 的 return 语 句 来 返回 一 个 值 。 


这 里 是 一 个 有 关 语句 列表 语法 的 示例 : 


array_map ($players, $player 一 > { 
Stotal = 0; 
foreach ($player->getScores() as $score) { 
Stotal += $score; 


return Stotal7 


1); 


为 了 弥补 通过 引用 进行 捕获 的 缺失 ， 这 里 有 个 小 小 的 提示 ， 你 可 以 使 用 通常 的 闭 包 语法 ， 而 不 是 拉 姆 达 表达 式 : 使 用 可 变 变量 。 语 言 的 运行 环境 必须 对 闭 包 体 进行 静态 地 观测 ， 然 后 决定 捕获 哪个 
量 。 而 在 可 变 变量 面前 ， 它 不 能 这 样 做 。 思 考 下 面 的 代码 : 


Sone = /* http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... */ 


S$other = /* http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... */ 
$local reader = function ($index) use ($one, $other) { 
Sname = ($index 一 = 0 ? 'one' ; 'other'); 


return $$name; 


a 


当 使 用 拉 姆 达 表 达 式 的 时 候 ， 语 言 的 运行 环境 将 无 从 得 知 它 应 该 捕获 $one 和 $other， 这 里 没有 任何 途径 告诉 它 。 如 果 你 把 示例 中 的 闭 包 改写 成 拉 姆 达 表 达 式 ， 那 么 对 于 拉 姆 达 表 达 式 的 内 部 来 
说 ，$one 和 $other 将 会 是 未 定义 的 。 那 么 对 它们 的 读 取 将 会 导致 一 个 “未 定义 变量 ”的 警告 。 


3.5 “构造 冰 数 参数 升级 


“构造 函数 参数 升级 ”是 个 简单 的 特性 ， 被 设计 用 于 减少 在 构造 函数 中 的 模板 代码 量 。 如 果 你 的 代码 库 大 量 使 用 类 ， 那 么 很 可 能 有 大 量 类 似 下 面 的 代码 : 


class Employee { 
Private $id; 
private $name; 
private $department; 


public function _construct ($id, $name, $department) { 
Sthis->id = $id; 
Sthis->name = $name; 
$this->department = $department; 
’ 
LE: 


这 是 很 糟糕 的 ， 因 为 每 个 类 需要 存储 的 东西 在 四 个 地 方 都 是 重复 的 : 一 个 是 属性 ， 一 个 是 构造 函数 的 参数 ， 还 有 两 个 是 在 构造 函数 体内 的 赋值 表达 式 。 “构造 函数 参数 升级 ”把 上 述 四 部 分 减少 为 一 部 
分 。 上 述 代码 可 以 像 下 面 一 样 进行 改写 : 


class Employee { 
// 这 里 有 


public function _ construct (private $id, private $name, private $department) { 
// 这 里 有 
} 
} 


语法 是 非常 简单 的 : 你 需要 做 的 所 有 的 事情 就 是 在 构造 函数 的 参数 前 面 增加 访问 修饰 符 关 键 词 (private、protected 或 者 public) 。 这 些 升 级 的 参数 可 以 和 普通 的 参数 并 存 ， 并 且 它 们 可 以 交 蔡 使 用 。 


除了 构造 函数 参数 声明 ， 该 语法 声明 了 一 个 和 给 定 的 访问 修饰 符 一 致 的 属性 ， 并 把 实 参 分 配 在 属性 上 。 你 还 可 以 在 构造 函数 体内 编写 代码 ， 当 上 述 操作 完成 后 ， 这 些 代 码 仍然 会 运行 。 


这 和 类 型 标注 是 兼容 的 : 只 需要 类 型 标注 放置 于 访问 修饰 符 和 参数 名 之 间 即 可 。 这 个 类 型 标注 将 同时 作用 于 属性 及 对 应 参数 。 你 还 可 以 对 升级 版 的 参数 设置 默认 值 : 


class User { 
public function _ construct (Private int $id, private string Sname = '') { 
} 

} 


属性 (attribute) 是 个 语法 扩展 ， 这 项 扩展 可 以 使 你 对 函数 、 方 法 、 类 、 接 口 还 有 trait 添 加 元 数据 。 然 后 添加 一 般 的 PHP 的 反射 AP1， 就 可 以 访问 这 些 元 数据 了 。 


属性 是 结构 化 的 信息 替代 ， 通 常用 于 文档 注释 的 编码 。 它 通过 反射 的 编程 方式 变 得 可 用 ， 从 而 替代 了 要 求 一 个 独立 的 程序 去 解析 这 个 信息 。 这 里 有 一 个 例子 ， 用 于 和 解释 在 文档 注释 中 使 用 它 : 


xx 
* MyFeatureTestCase 
和 
* @owner oyamauchi 
* @deprecated 
Ee 


class MyFeatureTestCase extends TestCase { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 


/** 


* MyFeatureTestCase with attributes 
要 下 


<<Owner ('oyamauchi'), Deprecated>> 
class MyFeatureTestCaseWithAttributes extends TestCase { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


3.6.1 属性 语 ; 


每 个 属性 都 是 key 到 | 数组 中 value 的 映射 。key 都 是 字符 串 ， 而 value 是 标量 (null、 布 尔 型 字面 量 、 数 字 型 字面 量 、 字 符 串 字面 量 ， 或 者 它们 的 数组 ) 。 


语法 非常 简单 ， 在 一 个 函数 、 方 法 、 类 、 接 口 或 者 trait 前 面 ， 放 置 属性 值 到 两 对 尖 括 号 内 部 即 可 。 在 最 简单 的 情况 下 ， 每 个 属性 仅仅 是 个 key (一 个 不 带 引号 的 字符 串 ) : 


<<DarkMagic>> 
function summon demon () { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


Nn 果 属 性 的 key 是 以 两 个 下 划 线 开头 ， 这 些 key 是 被 运行 环境 和 类 型 检查 器 保留 的 特殊 用 途 。 三 个 上 述 属 性 存在 于 Hack/HHVM 3.6( 将 在 下 一 节 中 进行 描述 ) ， 这 里 将 会 有 更 多 的 内 容 。 


为 了 访问 这 些 属性 ， 可 以 使 用 方法 getAttributes () 或 者 getAttribute () ， 上 述 方 法 存在 于 ReflectionFunction 中 (ReflectionClass 和 ReflectionMethod 存 在 着 相同 的 方法 ) : 


$function = new ReflectionFunction('summon demon'); 


echo "All attributes: \n"; 
var_ dump ($function->getAttributes ()) 7 


echo "Just DarkMagic: \n"; 
var dump ($function->getAttribute('DarkMagic')); 


All attributes: 
array(1) { 
["DarkMagic"]=> 
array(0) { 
} 


} 

Just DarkMagic: 
array(0) { 

} 


如 果 你 调用 getAttribute () 方法 来 读 取 一 个 并 不 存在 的 属性 ， 它 将 会 返回 null 并 且 不 会 引发 错误 。 除 此 之 外 ， 调 用 方法 getAttribute ($name) 其 实 就 相当 于 我 们 调用 了 方法 getAttributes () ， 然 
后 把 $name 索 引 至 返回 的 数组 中 : 


<<Magic ('dark')>> 
function summon demon () { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


<<Magic('curse', 'dark')>> 
function banish to eternal void() { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


$function = new ReflectionFunction('banish to eternal void'); 


var_dump ($function->getAttributes ()); 


array(1) { 
["Magic"]=> 
array(2) { 
0]=> 
string(5) "curse" 
1]=> 


string(4) "dark" 


在 使 用 它们 之 前 ， 你 不 必 四 处 去 声明 属性 的 名 字 。 它 们 仅仅 是 可 解析 的 注释 而 已 。 


3.6.2 ”特殊 属性 


这 里 有 三 个 被 Hack 类 型 检查 器 和 HHVM 特 殊 对 待 的 属性 ， 它 们 名 字 之 中 两 个 连续 的 下 划 线 表明 它们 是 特殊 的 〈 这 个 约定 是 为 特殊 内 置 属性 的 应 用 保留 的 ) : 


__ Override 


当 这 个 属性 被 应 用 到 一 个 方法 时 ，Hack 的 类 型 检查 器 会 检查 这 个 方法 正在 覆盖 一 个 从 某 祖先 类 继承 的 方法 。 如 果 这 不 是 一 个 覆盖 的 话 ， 类 型 检查 器 将 会 报告 一 个 错误 。 值 得 注意 的 是 ， 被 覆盖 的 方法 必 
须 在 一 个 Hack 文 件 之 中 。 如 果 被 覆盖 的 方法 在 PHP 文 件 中 ， 类 型 检查 器 将 看 不 到 它 ， 所 以 会 报告 一 个 错误 。 


_ Override 属 性 还 可 以 应 用 到 在 trait 中 设置 的 方法 ， 而 对 于 trait 本 身 来 说， 这 个 限制 并 不 会 执行 ， 但 是 当 这 个 trait 在 任何 类 中 使 用 的 时 候 ， 这 个 限制 属性 将 会 生效 。 这 和 trait 的 “复制 粘贴 ”的 语义 保 
持 一 致 。 


HHVM 并 不 会 对 这 个 属性 特殊 对 待 ， 这 不 会 引发 任何 运行 时 错误 。 


__ ConsistentConstruct 


在 Hack 中 ， 一 个 子 类 的 _construct () 方法 不 必 符合 父 类 的 _construct () 方法 。 这 是 刻意 为 之 的 。 这 里 有 充足 的 理由 让 我 们 相信 ， 一 个 子 类 拥有 不 同 于 其 构造 函数 的 需求 。 然 而 这 样 可 以 隐藏 问 
题 。 就 像 在 new static () 中 一 样 ， 这 种 构造 函数 被 称 为 多 态 。 


下 面 是 在 工厂 模式 下 的 好 例子 。 接 下 来 的 例子 将 展示 一 个 拥有 很 多 静态 工厂 方法 的 抽象 基础 类 ， 它 们 中 的 每 一 个 都 调用 new static () 。 每 个 子 类 都 应 该 用 相同 的 签名 实现 一 个 构造 函数 : 


<<_ ConsistentConstruct>> 
abstract class Reader { 
protected function _construct (resource $file) { } 


public static function fromFile (string $path): this { 
return new static (fopen ($path, 'r')); 


} 


public static function fromString(string $str): this { 
$tmpfile = tmpfile(); 
fwrite ($tmpfile, $str); 
fseek ($tmpfile, 0); 
return new static($tmpfile); 
¢ 
abstract public function readItem(): mixed; 


bE: 


class BufferedReader extends Reader { 
protected function _construct (resource 人 人 el + 
// 填充 buffer http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


public function readItem(): mixed { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 
} 


class TokenReader extends Reader { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 


没有 _ConsistentConstruct 的 话 ， 一 个 子 类 将 会 有 错误 的 构造 函数 签名 ， 并 且 Hack 的 类 型 检查 器 将 不 会 对 此 报告 一 个 错误 。 因 为 类 型 检查 器 不 能 够 分 辨 哪个 构造 函数 将 涉及 new static () 调 


并 不 能 对 这 个 调用 进行 充分 的 类 型 检查 。 但 是 使 用 _ConsistentConstruct， 类 型 检查 器 将 会 报告 一 个 “构造 器 不 匹配 签名 ”的 错误 ， 这 样 你 就 可 以 间接 知道 new static () 调用 是 类 型 安全 的 了 。 


出 


这 个 属性 仅仅 对 于 类 型 检查 器 有 重大 意义 ， 而 HHVM 并 不 特别 对 待 它 。 


_ Memoize 


并 不 像 其 他 两 个 特殊 属性 ， 这 个 属性 被 HHVM 特 殊 对 待 而 被 类 型 检查 器 所 忽略 。 这 个 属性 让 你 使 用 memoization (备忘录 ) 的 普通 模式 ， 在 运行 环境 的 帮助 下 ， 它 将 比 单独 在 PHP 或 者 Hack 代 码 中 更 


有 效率 。 


memoization 是 缓存 耗 时 计算 结果 的 一 种 模式 。 它 经 常 以 下 面 的 代码 实现 : 


function factorize impl ($num) { 
// Some factorization algorithm 


} 


function factorize(Snum) { 
static $cache = array(); 
if (!isset($cache[$num])) { 
$cache [Snum] = factorize impl ($num); 


return $cache[$num]; 


bE: 


上 述 例子 中 的 大 多 数 代码 都 是 样板 ， 并 且 _Memoize 属 性 使 你 移 除 所 有 的 一 切 。 这 里 是 另 一 个 选择 ， 可 以 让 运行 环境 负责 管理 你 的 缓存 : 


咒 


允许 删除 缓存 中 的 实体 。 事 实 上 ， 这 就 是 相对 于 实现 memoization 本 身 ， 使 用 _Memoize 属 性 的 优势 。 


<<_ Memoize>> 
function factorize(Snum) { 
// Some factorization algorithm 


} 

你 可 以 备 忘 (memoize) 函数 或 者 方法 ， 但 是 这 里 有 一 些 限制 : 
“ 你 不 可 以 备 忘 可 变 函 数 ( 例 如 : 实 参数 量 可 变 的 函数 ) 。 

-你 不 可 以 备 忘 使 用 引用 作为 实 参 的 函数 。 


“ 对 于 被 备 忘 的 函数 来 说 ， 所 有 实 参 都 必须 是 如 下 类 型 中 的 一 个 : bool、int、float、stting、 上 述 类 型 的 nullable 版 本 、 一 个 实现 了 特殊 接口 IMemoizeParam 类 的 对 象 ， 或 者 上 述 类 型 的 一 个 数组 或 者 集合 。 


IMemoizeParam 声 明了 一 个 单独 非 静 态 的 方法 getlnstanceKey () : string。 这 个 方法 的 工作 就 是 转化 一 个 对 象 到 一 个 字符 串 ， 以 便于 该 字符 串 能 够 作为 一 个 数组 的 key 在 memoization 中 缓存 。 


在 使 用 _Memoize 的 时 候 ， 有 很 多 事情 需要 注意 。 首 先 注意 这 是 个 时 间 和 内 存 的 权衡 。 它 可 以 通过 降低 计算 的 数量 来 使 代码 运行 得 更 快 ， 但 是 这 样 同时 会 增加 内 存 的 开销 。 所 以 这 并 不 总 是 会 令 人 满 


其 次 ，HHVM 并 不 对 它 何 时 将 实际 执行 一 个 备 忘 的 函数 进行 担保 ， 与 之 相对 的 是 ， 仅 仅 从 缓存 中 返回 一 个 值 。 不 要 假设 对 于 给 定 的 实 参 ， 该 函数 体 仅 会 执行 一 次 。 例 如 ， 出 于 释放 内 存 的 目的 ，HHVM 


最 后 值得 注意 的 是 ，HHVM 并 不 会 试图 确认 备 忘 的 函数 不 会 有 副作用 。 或 者 说 对 于 相同 的 实 参 ， 无 论 它 被 调用 多 少 次 ， 都 会 得 到 同样 的 结果 。 对 于 一 个 备 忘 的 函数 来 阅 ， 所 有 这 些 属性 都 非常 重要 。 如 


果 没 有 它们 ，memoization 可 能 会 明显 地 改变 程序 的 行为 。 


3.7 ”加 强 的 自动 加 载 


载 。 


通过 函数 _autoload () 和 spl_autoload register () 函数 ，PHP 对 类 提供 自动 加 载 功 能 ， 并 且 HHVM 也 支持 这 个 特性 。HHVM 还 提供 一 个 附加 的 特性 允许 对 PHP 和 Hack 的 函数 及 常量 进行 自动 加 
同时 在 Hack 中 ， 提 供 对 类 型 别名 的 自动 加 载 功能 (具体 参见 3.2 节 的 内 容 ) 。 


这 个 特性 相对 于 PHP 的 自动 加 载 机 制 有 着 另外 的 过 人 之 处 : 它 可 以 不 运行 任何 PHP 代 码 就 可 以 工作 ， 所 以 性 能 上 一 般 更 好 。 在 运行 环境 中 ， 仅 仅 通 过 对 两 个 哈 希 表 的 查找 ， 一 个 成 功 的 自动 加 载 就 可 以 


全 部 执行 完毕 。 正 是 出 于 这 个 原因 ， 如 果 你 正在 使 用 HHVM ， 强 烈 建议 你 使 用 这 个 特性 蔡 代 PHP 的 自动 加 载 机 制 。 


此 加 强 的 自动 加 载 的 接口 就 是 存在 于 命名 空间 HH 中 的 函数 autoload _set_paths () 。 它 接受 两 个 实 参 : 一 个 自动 加 载 映射 (这 是 个 数组 ) ; 另 一 个 为 根 路 径 (这 是 个 字符 串 ) 。 当 HHVM 需 要 自动 加 


载 什 么 时 ， 它 将 会 在 自动 加 载 映 射 中 进行 查找 。 


自动 加 载 映 射 是 个 数组 。 这 里 有 五 个 重要 的 可 选 字符 串 key: 


“ 键 'class'、'function'、"contstant 还 有 'type' 每 个 都 映射 到 数组 。 这 些 内 部 数组 叫做 子 图 (submap) ， 拥 有 实体 (分 别 是 类 、 函 数 、 常 量 和 类 型 ) 名 称 作为 key， 而 对 应 的 value 存 放 的 是 能 够 被 发 现 的 相应 实 
体 的 文件 路 径 。 


“ 键 failure' 映 射 到 一 个 callbale 的 值 ， 也 就 是 失败 回调 〈the failure callbak) ， 如 果 在 上 述 key 上 进行 查找 都 失败 了 的 话 ， 就 会 调用 它 。 


这 里 有 个 例子 ， 演 示 了 如 何 建立 一 个 自动 加 载 映射 ， 并 且 调 用 一 个 没有 加 载 的 函数 。 


function autoload fail (string $kind, string $name): ?bool { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


function setup autoloading(): void { 
Smap = array( 
"function' => array('extricate' => 'lib/extricate.php') 


) 7 


HH\autoload set paths (Smap，_DIR  . '/'); 


SetuPp_autoloading () 7 
extricate(); 


当 函 数 extricate () 被 调用 的 时 候 ， 运 行 环境 在 自动 加 载 映射 中 的 'function 子 图 对 'extricate 进行 入 口 查找 。 当 它 找 到 入 口 后 ， 它 将 附加 对 应 的 路 径 到 根 路 径 ， 然 后 在 合并 的 路 径 中 加 载 对 应 的 文件 ， 
并 且 继 续 执行 。 


如 果 上 述 过 程 中 的 某 些 步骤 失败 了 ， 比 如 function 子 图 并 不 能 显示 ， 或 者 'extricate 入 口 不 能 显示 ， 或 者 文件 并 不 存在 ， 或 者 对 应 的 文件 并 不 包含 函数 extricate () 的 定义 ， 那 么 失败 回调 函数 就 会 被 
调用 。 如 果 它 返回 真 ， 那 么 运行 环境 假设 失败 回调 函数 加 载 了 它 ， 将 会 再 次 试图 调用 extricate () 函数 。 如 果 它 并 没有 这 么 做 ， 或 者 失败 回调 函数 返回 了 false 或 者 null， 那 么 运行 环境 将 声明 失败 ， 并 且 提 
出 一 个 未 定义 函数 的 致命 错误 。 


失败 回调 函数 接受 两 个 实 参 : 首先 ， 一 个 标识 了 被 自动 加 载 的 实体 类 别 的 字符 串 (例如 'class'、'function'`、'constant' 或 者 'type') ， 其 次 ， 一 个 用 于 表示 实体 名 字 的 字符 串 。 


理解 整个 算法 最 直观 明了 的 办 法 就 是 通过 流程 图 进行 演示 ， 请 参见 图 3-1。 


图 3-1: 自动 加 载 一 个 函数 
这 里 有 两 种 情况 ， 算 法 可 能 会 稍稍 不 同 : 


“ 如 果 被 自动 加 载 的 实体 是 类 ， 那 么 失败 回调 函数 返回 fse 将 有 别 于 返回 nul。 如 果 失 败 回 调 函数 返回 false， 那 么 接 下 来 的 行为 将 会 和 函数 的 情况 一 样 : 马上 提出 一 个 致命 错误 。 但 是 如 果 失 败 回调 函数 
返回 null，HHVM 将 会 退回 到 标准 的 PHP 自 动 加 载 机 制 : _autoload () 和 SPL 自 动 加 载 队 列 。 


“ 如 果 被 自动 加 载 的 实体 是 类 型 别名 ，HHVM 将 会 首先 尝试 在 'class' 的 子 图 中 进行 查找 ， 然 后 是 'type' 的 子 图 ， 然 后 是 第 一 实 参 'class' 的 失败 回调 ， 然 后 是 第 一 个 实 参 为 'type' 的 失败 回调 。 这 是 因为 任何 可 能 
是 类 型 别名 的 实体 也 可 能 是 个 类 。 一 个 实体 自动 加 载 的 唯一 可 能 是 类 型 别名 是 一 个 参数 类 型 标注 或 一 个 返回 类 型 标注 的 执行 期 间 。 


最 后 一 点 失败 回调 在 实际 加 载 过 程 中 ， 不 应 该 被 常态 化 地 使 用 。 大 多 数 情况 下 ， 它 应 该 用 于 错误 记录 。 如 果 运 行 环境 需要 回 退 到 失败 回调 ， 整 个 自动 加 载 的 过 程 将 会 变 慢 。 


3.8 ”整数 算术 溢出 


在 PHP 中 ， 如 果 整 数 算术 操作 溢出 了 ， 结 果 将 变 为 一 个 浮 点 数 : 


var Gump (PHP INT MAX + 1); // float (9.2233720368548E+18) 


这 将 是 一 个 很 糟糕 的 体验 ， 意 味 着 程序 内 几乎 所 有 的 算数 运算 都 必须 对 溢出 进行 检测 ， 甚 至 在 实际 中 基本 不 可 能 发 生 溢出 的 情况 下 也 是 。 从 程序 逻辑 立场 上 来 说 ， 这 也 是 可 疑 的 : 在 先前 
PHP_INT_MAX+1 的 例子 中 ， 对 浮 点 数 的 转化 将 会 立即 导致 精确 度 的 丢失 。 


HHVM 包 含 一 种 模式 ， 让 整数 算术 溢出 在 运行 环境 中 遵循 二 次 补 码 运算 的 规则 。 这 就 意味 着 两 个 整数 的 加 法 、 减 法 ， 或 者 乘法 的 结果 总 是 一 个 整数 中。 开启 这 种 模式 的 配置 选项 是 


hhvm.ints_ overflow to _ints。 


事实 上 ，Hack 的 类 型 检查 器 对 待 整数 算法 运算 的 时 候 ， 总 是 认为 它们 遵从 二 次 补 码 运算 规则 ， 并 且 这 不 可 配置 。 一 个 理由 就 是 ， 类 型 检查 器 遵从 PHP 的 行为 ， 这 将 对 算术 运算 的 结果 进行 有 意义 的 类 型 
得 很 困难 。 除 此 之 外 ， 在 任何 其 他 的 主流 编程 语言 中 ， 这 种 溢出 变 浮 点 数 的 行为 是 不 存在 的 ， 并 且 对 于 PHP 的 初学 者 来 说 ， 常 让 人 感到 不 可 思议 。 


四] 精确 的 措辞 是 “整数 在 加 法 、 减 法 和 乘法 上 都 是 闭合 的 ”。 (The mathematical phrase is “integers are closed under addition,subtraction,and multiplication.” ) 


3.9 ”nullsafe 方 法 调用 操作 


对 于 一 个 可 能 为 null 的 对 象 ， 进 行 方法 调用 的 时 人 息 ，Hack 增 加 了 一 个 新 的 操作 符 。 这 个 操作 符 就 是 ?->， 与 常用 的 调用 操作 符 -> 相对 应 : 


interface Reader { 
public function readAll(): string; 
} 


function read everything(?Reader $reader): ?string { 
return S$reader?->readAll (); 


} 


如 果 该 操作 符 左 手边 的 值 是 null， 这 里 将 不 会 有 任何 警告 或 者 错误 ， 并 且 整 个 表达 式 将 会 被 执行 为 null。 因 此 ， 这 种 表达 式 的 类 型 是 实际 方法 返回 类 型 的 可 空 版 本 。 


这 种 操作 符 对 于 链 式 方法 调用 非常 适合 


因为 它 允 许 链 中 的 任何 方法 返回 null， 而 无 需 对 null 检 查 每 一 处 ， 即 使 对 于 BadMethodCallException 来 说 也 是 安全 的 。 例 如 : 


$name = $comment?->getPost () ?->getAuthor () ?->getName (); 


3.10 trait 和 接口 的 必要 条 件 


trait 是 类 型 检查 器 最 为 棘手 的 区 域 之 一 。 一 个 trait 基 本 上 来 说 是 从 上 下 文中 取出 来 的 代码 段 。 如 果 想 要 起 作用 ，trait 必 须 能 够 触及 到 那些 它们 没有 定义 的 属性 和 方法 ， 而 这 些 将 会 由 使 用 trait 的 类 来 提 


供 


No 


为 了 对 trait 进 行 更 强 有 力 的 类 型 检查 ，Hack 提 供 了 一 个 特性 来 使 你 能 够 限制 什么 样 的 类 可 以 使 用 trait。 在 一 个 trait 的 定义 内 部 ， 你 可 以 明确 地 指出 任何 使 用 这 个 trait 的 类 都 必须 继承 自 某 个 类 ， 或 者 实 
现 某 个 特定 的 接口 。 这 样 的 话 ， 类 型 检查 器 就 可 以 通过 在 trait 中 被 允许 使 用 的 类 或 者 接口 的 上 下 文 ， 来 检测 这 个 trait 中 的 属性 访问 或 者 方法 调用 。 


语法 是 require extends ClassName 或 者 require implements InterfaceName。 这 些 语句 都 将 放置 在 trait 定 义 的 顶层 位 置 : 


class C { 
Public function methodFromClass(): void { } 


interface I{ 
Public function methodFromInterface () : void 


trait NoRequire { 
public function f(): void { 


$this->methodFromInterface(); // 错误 : 不 能 找到 方法 
$this->methodFromClass (); // 错误 : 不 能 找到 方法 


} 
} 


trait HasRequire { 
require extends C; 
require implements I; 


Public function f(): void { 
Sthis->methodFromInterface () ;// OK 
Sthis->methodFromClass ()7// OK 

小 


如 果 一 个 类 使 用 了 一 个 trait， 但 并 不 能 满足 trait 的 基本 要 求 ， 那 么 类 型 检查 器 将 会 报告 一 个 错误 。 我 们 继续 上 一 个 例子 : 


class Bad { 
use HasRequire;// 错误 : 不 能 满足 必要 条 件 


值得 注意 的 是 ，require extends 真 实意 味 着 extends。 这 就 是 说 ， 对 于 出 现在 trait 的 require extends 声 明之 中 的 类 ， 如 果 对 应 的 类 使 用 这 个 trait， 将 会 引发 一 个 错误 。 使 用 这 个 trait 的 任何 类 都 必须 是 
相关 的 派生 类 : 


trait T { 


require extends C; 


} 


class Cf{ 
use T; // 错误 


} 


除了 这 些 声明 ，Hack 还 允许 trait 实 现 接口 。 当 使 用 一 个 实现 了 某 个 接口 的 trait 时 ， 它 将 表现 为 好 像 实现 的 声明 传递 给 了 使 用 这 个 trait 的 类 ， 并 且 所 有 伴随 的 限制 都 将 会 执行 。 这 和 在 trait 
implements 的 效果 是 一 样 的 : 


中 使 用 require 


interface I 1{ 
public function methodFromIinterface(): void; 


i 


trait T implements I { 
public function f(): void { 
$this->methodFromInterface ();// OK 
} 
} 


class C { 
use T; // 错误 : 必须 提供 methodFromInterface() 方 法 的 实现 
} 


最 终 ，require extends 在 接口 中 也 可 以 正常 工作 。 只 有 从 被 命名 的 类 继承 的 类 才 允 许 实现 这 个 接口 (再 一 次 ， 这 排除 了 被 命名 类 自身 ) : 


interface I 1{ 
require extends ParentClass; 
} 
class ParentClass { 
// 这 个 类 如 果 要 实现 接口 T， 这 里 将 会 发 生 一 个 错误 
} 


class ChildClass extends ParentClass implements I { // OK 
i 


class OtherChild implements I { // 错 误 


3.11 ”隐藏 类 型 检查 器 错误 


假设 你 有 个 核心 函数 ， 没 有 类 型 标注 ， 在 代码 库 中 四 处 被 使 用 ， 并 且 你 希望 对 它 添加 个 标注 。 这 可 能 导致 大 量 函 数 调用 点 的 类 型 错误 提示 。 类 型 检查 器 提供 给 你 可 用 任何 方法 向 这 个 核心 函数 添加 标 
注 ， 并 且 隐 藏 在 每 个 调用 点 的 错误 提示 。 这 样 的 话 ， 你 可 以 让 标注 添加 进去 (这 样 的 话 ， 新 的 使 用 该 函数 的 代码 才能 是 类 型 良好 的 ) 的 同时 ， 保 持 错误 信息 的 干净 ， 并 且 你 需要 修复 的 地 方 非常 容易 找到 。 


这 个 就 是 “HH_FIXME” 注 释 的 目的 所 在 。 


类 型 检查 器 报告 的 每 个 错误 信息 都 有 一 个 数字 的 错误 码 ， 在 错误 信息 的 尾部 显示 。 例 如 ， 思 考 下 面 的 代码 : 


<?hh // strict 


function core function(): int { 
return 123; 


i 


function some other(): string { 
return core function 站 


} 


那么 从 类 型 检查 器 将 会 生成 下 列 错误 信息 : 


/home/oyamauchi/hack/test.Php:8:10,24: Invalid return type (Typing[4110]) 
/home/oyamauchi/hack/test .php:7:24,29: This is a string 
/home/oyamauchi /hack/test .php:3:27,29: It is incompatible with an int 


从 上 边 错 误 信息 的 圆 括号 里 面 可 以 看 到 ， 这 里 的 错误 码 是 4110。 (“Typing” 这 个 词 仅仅 指出 错误 所 在 分 类 目录 ， 并 不 是 错误 码 的 一 部 分 。 在 所 有 的 分 类 目录 中 只 有 一 个 错误 码 4110。) 


如 果 想 隐藏 这 个 错误 ， 那 么 就 需要 在 函数 签名 或 者 return 语 句 前 面 ， 添 加 一 个 注释 /*HH_FIXME[4110]*/。 当 然 ， 你 还 需要 在 结束 的 方 括号 后 面 添 加 些 解释 性 的 信息 ， 说 明 一 下 为 什么 隐藏 


接 下 来 的 ome_other () 函数 的 任何 版 本 都 隐藏 错误 信息 : 


这 个 错误 信 


function some other () : int { 
/* HH FTXMET4110] 来 自 core_function 的 返回 类 型 */ 
return core function 人 人 


} 


function some other(): string { 
/* HH_FIXMET4110] 来 自 core_function 的 返回 类 型 */ return core function(); 
: 


/* HH FIXME[4110] 来 自 core_function 的 返回 类 型 */ 
function some other(): string { 
return core function(); 


} 


/* HH _FIXME[4110] core_ function 返 回 类 型 */ function some other(): string { 
return core function Cs 


bE: 


这 个 注释 的 语法 是 非常 精密 的 。 它 必须 是 C 风 格 的 /**/ 注 释 ; 而 shell 风 格 的 瞧 主 释 和 C++ 风格 的 /注释 都 不 工作 。 同 时 ， 它 还 必须 以 HH_FIXME 开 头 ， 然 后 在 方 括号 里 面 放置 相关 的 错误 码 。 


一 个 “HH_FIXME” 就 可 以 隐藏 给 定 的 错误 。 这 个 作用 域 范围 是 该 注释 后 的 非 空 的 、 非 注释 的 代码 行 。 在 先前 的 例子 中 ， 这 里 有 两 部 分 代码 同时 作用 来 引发 相关 的 错误 : return 语 句 和 返回 类 型 标注 。 


那么 隐藏 任何 一 部 分 的 错误 信息 都 会 隐藏 所 有 的 错误 信息 。 


可 以 在 有 问题 的 代码 前 使 用 多 条 单独 成 行 的 HH_FIXME 注 释 。 例 如 下 面 的 代码 : 


function f(?void Snonsense) : int { 
return "oops' 7 


将 会 产生 如 下 的 错误 输出 : 


/home/oyamauchi/Vtest.php:2:12,16: ?void is a nonsensical typehint (Typing[4066]) 

/home/oyamauchi/test .php:3:10,11: Invalid return type (Typing[4110]) 
/home/oyamauchi/test .php:2:26,28: This is an int 
/home/oyamauchi/Vtest.php:3:10,11: It is incompatible with a string 


如 果 想 使 所 有 的 错误 都 隐藏 的 话 ， 那 么 可 以 这 样 写 : 


/* HH_FIXME[4110] 仅 是 个 例子 */ 

/* HH FIXME[4066] 仅 是 个 例子 */ 

function f(?void Snonsense) : int { 
return "oops'7 


} 


只 有 在 上 述 注释 中 被 特别 指明 的 错误 代码 才 会 被 隐藏 ， 这 点 非常 完美 。 如 果 其 他 类 型 错误 在 被 隐藏 的 代码 行内 触发 ， 你 仍然 可 以 看 到 相关 的 错误 信息 。 错 误 码 在 类 型 检查 器 的 各 个 版 本 中 将 会 保持 稳 
定 ， 所 以 这 些 注释 在 新 的 版 本 中 将 会 兼容 。 


第 4 章 ”在 Hack 中 不 支持 的 PHP 特 性 


Hack 有 着 很 多 PHP 所 不 支持 的 特性 ， 但 是 同时 也 丢失 了 对 一 些 PHP 特 性 的 支持 。 省 略 掉 这 些 特性 的 支持 ， 并 非 轻易 做 出 的 决定 : 在 它们 后 面 存在 着 深层 次 的 技术 原因 ， 即 基于 对 类 型 安全 和 性 能 表现 上 
的 关注 。 


非常 重要 的 一 点 是 所 有 的 限制 都 针对 Hack 做 出 。 当 HHVM 运 行 PHP 代 码 的 时 候 (任何 以 <? php 开 头 的 文件 ) ， 它 将 产生 和 来 自 PHP.net 的 官方 编译 器 一 致 的 结果 。 对 于 使 用 了 Hack 中 所 不 支持 的 特性 
的 PHP 代 码 ， 仍 然 可 以 和 Hack 代 码 无 颖 对 接 。 


在 本 章 的 学 习 中 ， 我 们 将 对 那些 不 支持 的 特性 进行 探索 ， 分 析 为 什么 它们 很 难 或 者 不 可 能 去 实现 静态 类 型 分 析 ， 并 且 为 什么 它们 非常 难 编译 成 高 效 的 原生 代码 。 如 果 你 仅仅 是 简单 地 寻求 从 Hack 开 始 学 
习 ， 那 么 你 仅仅 浏览 一 下 本 节 的 题目 就 可 以 了 。 


再 次 澄清 一 下 ， 如 果 运 行 正常 的 PHP 代 码 ，HHVM 支 持 所 有 的 特性 。 


4.1 引用 


Hack 不 支持 的 特性 之 中 ， 引 用 是 最 基础 的 部 分 。 它 们 是 一 个 非常 具有 代表 性 的 语言 特性 ， 在 很 多 方面 都 对 PHP 有 着 很 深 的 影响 力 。 主 要 有 PHP 引 擎 如 何 表示 程序 值 、 如 何 处 理 一 个 变量 、 函 数 调用 和 返 
回 机 制 和 内 存 管 理 。 


引用 将 导致 很 难 进行 彻底 的 静态 编译 。 它 们 允许 “超越 作用 ”的 可 能 性 ， 而 那些 看 起 来 无 伤 大 雅 的 代码 都 可 能 有 未 知 的 影响 。 通 过 引用 传递 一 个 变量 到 一 个 函数 的 话 ， 就 意味 着 任何 事情 都 可 能 在 这 个 
变量 上 发 生 ， 并 且 类 型 检查 器 无 从 得 知 具体 发 生 了 什么 (因为 类 型 推断 基于 函数 本 地 ， 详 见 1.6.3 节 的 相关 内 容 ) 。 这 就 导致 对 于 引用 ， 我 们 无 法 确保 类 型 安全 ， 并 且 无 法 对 它们 周围 的 代码 进行 有 效 地 执 


行 。 


另外 一 个 “超越 作用 ”使 得 类 型 推理 更 加 困难 的 例子 ， 就 是 对 象 属性 的 问题 。 正 如 我 们 在 1.7.4 节 所 看 到 的 一 样 ， 类 型 检查 器 对 于 对 象 属性 的 推理 是 很 保守 的 。 这 是 因为 有 非常 多 的 途径 可 以 远 距离 改变 
对 象 的 属性 。 当 使 用 引用 的 时 候 ， 这 种 情况 将 变 得 更 加 糟糕 ， 这 就 是 Hack 直 接地 忽略 了 它们 的 原因 。 


这 里 还 有 个 单独 的 方式 来 说 明 “ 为 什么 引 3 致 较 差 的 性 能 ”: 相 较 访问 一 个 普通 的 变量 而 言 ， 访 问 一 个 本 身 为 引用 的 变量 还 需要 一 个 特殊 附加 的 指针 间接 引用 。 这 就 意味 着 更 多 的 内 存 访问 ， 将 给 
缓存 带 来 更 多 的 压力 ， 并 且 导 致 了 主 存储 器 的 更 多 切换 。 


垃圾 回收 


另外 一 个 导致 引用 很 麻烦 的 事情 就 是 : 它 允 许 PHP 代 码 通 过 对 数组 中 一 个 元 素 的 引用 ， 来 监控 运行 时 数组 复制 的 写 时 复制 优化 。 和 暂且 不 谈 在 哲学 上 关于 “这 为 什么 不 好 ”的 争论 ， 这 里 还 有 个 实践 上 的 
问题 : 事实 表明 ，PHP 代 码 对 写 时 复制 的 观测 ， 叶 致 非常 难于 (并 非 不 可 能 ) 实现 在 PHP 引 擎 中 追踪 垃圾 回收 进 制 。 


从 现状 来 看 ， 如 果 PHP 引 擎 不 使 用 单纯 引用 计数 的 话 ， 它 们 将 导致 可 观察 到 的 行为 差异 (这 也 称 为 bug) 。 这 就 意味 着 有 很 少 的 自由 可 以 实验 其 他 的 内 存 管理 算法 ， 这 也 就 切断 了 显著 提升 性 能 的 可 能 


4.1.1 全 局 声明 


局 声明 在 Hack 中 被 禁止 ， 因 为 它 从 底层 上 来 说 是 通过 引用 来 实现 的 。global$x 实 际 上 仅仅 是 “$x=&$GLOBALS['x]” 的 语法 糖 。 


在 局 部 模式 下 ， 你 可 以 不 使 用 3 引 


就 对 $GLOBALS 数 组 进行 读 写 。 所 以 你 可 以 利用 这 点 来 弥补 全 局 声明 的 缺失 。 (在 严格 模式 下 ，Hack 会 报告 一 个 错误 ,说 $GLOBALS 是 个 未 定义 的 变量 。) 


4.1.2 ”顶层 代码 


作为 对 全 局 声明 禁用 的 一 个 必然 结果 ， 在 严格 模式 下 大 多 数 的 顶层 代码 将 被 禁用 (在 局 部 模式 下 是 允许 的 ， 但 并 不 会 对 其 进行 类 型 检查 ) 。 你 可 以 定义 命名 实体 (函数 、 类 等 ) ， 并 且 可 以 在 所 有 模式 
的 顶层 代码 下 ， 使 用 require 或 者 include 等 一 系列 语句 。 


这 仅仅 是 因为 顶层 代码 在 全 局 范围 内 存在 []， 所 以 对 一 个 局 部 变量 的 读 或 写实 际 上 都 是 对 全 局 变量 的 读 或 写 。 


你 可 以 简单 地 通过 把 它们 包 囊 在 一 个 函数 内 ， 把 不 依赖 于 全 局 范围 的 


页 层 代码 去 掉 。 如 果 相 关 顶 层 代 码 确实 依赖 于 全 局 范围 ， 它 们 需要 一 个 更 大 幅度 的 改写 ， 以 便 在 Hack 中 生效 。 


无 论 是 脚本 还 是 Web 应 用 ， 每 一 个 程序 都 是 从 顶层 代码 开始 执行 ， 所 以 每 个 程序 都 至 少 需要 一 个 局 部 模式 的 文件 作为 入 口 点 。 理 想 情况 下 ， 除 了 require 和 相关 定义 外 ， 这 个 局 部 模式 的 文件 将 仅仅 有 一 


个 顶层 代码 ， 也 就 是 对 一 个 程序 逻辑 主体 的 函数 调用 。 例 如 : 


<?hh 
require once 'lib/autoload.php'; 


function main() { 
setup autoload(); 
do initialization(); 
$controller = find controller(); 
$controller->execute (); 


} 


main(); 


四 或 者 不 依赖 于 这 个 文件 是 从 哪里 被 包含 的 ， 这 也 是 另外 一 个 难于 进行 类 型 检查 的 原因 。 


4.2 ”旧式 风格 构造 器 


一 个 旧式 风格 的 构造 器 是 一 个 和 封闭 类 同名 的 方法 : 


class Thing { 
public function Thing() { 
echo 'constructor!'; 
} 
} 


St = new Thing();??// 输出 'constructor!' 


这 种 设计 的 灵感 可 能 来 自 于 C++ 和 Java， 但 是 在 PHP 5 中 被 统一 的 构造 器 _construct 取 代 。Hack 不 支持 旧式 风格 的 构造 函数 ， 原 因 在 于 避免 由 见 余 特 性 带 来 的 潜在 的 混淆 局 面 。 


特别 是 存在 继承 的 情况 下 ， 新 老 风格 构造 器 的 相互 作用 是 复杂 和 不 一 致 的 ， 所 以 这 里 没有 任何 理由 同时 拥有 它们 。 


这 不 仅仅 是 Hack 进 行 了 改变 ， 在 PHP 将 来 的 发 行 版 中 给 将 会 移 除 对 老式 风格 构造 器 特性 的 支持 。 


4.3 不 区 分 大 小 写 的 名 称 查 找 


在 PHP 中 ， 函 数 和 类 名 称 都 是 不 区 分 大 小 写 的 。 这 就 是 说 ， 如 果 你 定义 了 一 个 函数 名 叫 compute， 你 可 以 通过 CoMPUtE () 来 调用 它 。 然 而 ， 如 果 你 试图 在 Hack 中 做 同样 的 事情 ， 类 型 检查 器 会 报告 
一 个 错误 ,说 函数 CoMpUtE 没 有 被 定义 。 


然而 值得 注意 的 是 ， 虽 然 Hack 是 大 小 写 敏感 的 ， 但 是 定义 两 个 函数 (或 者 两 个 类 等 ) 仅仅 是 名 字 大 小 写 不 同 的话 ， 仍 然 是 非法 的 。 这 是 因为 Hack 必 须 和 PHP 进 行 相互 操作 ， 所 以 关于 名 称 查找 操作 ， 
仍然 不 区 分 大 小 写 。 


这 条 限制 的 存在 事实 上 无 关 类 型 安全 或 者 性 能 表现 。 在 Hack 中 实现 不 区 分 大 小 写 名 称 查找 是 非常 简单 的 ， 并 且 这 并 不 会 影响 类 型 检查 器 做 类 型 推理 的 能 力 。 


相反 ， 这 是 一 个 哲学 上 的 选择 。 大 多 数 的 编程 语言 都 是 大 小 写 敏 感 的 ， 这 包括 PHP 的 精神 先驱 Perl|、C 和 Java。 这 可 以 使 得 代码 更 易于 “ 读 ”， 而 对 于 “ 写 ” 本 身 并 没有 什么 难度 上 的 增加 。 


在 性 能 表现 方面 ， 大 小 写 不 敏感 的 查找 比 大 小 写 敏 感 的 查找 略 输 一 筹 ， 这 是 因为 (在 不 区 分 大 小 写 时 ) ， 目 标 字符 串 在 哈 希 表 中 进行 查找 时 ， 作 为 一 个 key 必 须 经 过 大 小 写 的 标准 化 。 而 在 HHVM 中 ， 
这 当然 也 会 带 来 小 小 的 内 存 开 销 ， 因 为 每 个 函数 和 类 都 必须 从 源码 中 存储 原始 名 字 (为 了 在 错误 信息 及 反射 中 进行 使 用 ) 和 一 个 大 小 写 标准 化 版 本 的 名 字 (为 了 哈 希 表 查 找 使 用 ) 。 


4.4 可 变 变量 


可 变 变量 看 起 来 类 似 这 样 : 


Sname = 'x'; 
$x = 'well this is silly'; 
echo $$name;  // 输 出 'well this is silly' 


总 的 来 说 ， 这 在 Hack 中 是 不 允许 的 ， 因 为 围绕 这 样 一 个 构造 是 无 法 推断 其 类 型 的 。 当 一 个 类 型 检查 器 看 到 类 似 “$$name” 这 样 的 表达 式 时 ， 它 不 清楚 这 个 表达 式 的 类 型 是 什么 ， 或 者 无 法 判断 这 是 否 
是 个 有 效 的 变量 访问 。 


并 且 这 还 仅仅 是 对 一 个 可 变 变 量 读 取 的 例子 。 对 于 一 个 类 似 $$name=10 这 样 的 表达 式 ， 通 常 可 以 在 作用 域内 改变 任何 一 个 局 部 变量 的 类 型 ， 并 且 类 型 检查 器 没有 理解 可 能 造成 影响 的 可 能 。 


这 一 推理 呼应 了 “为 什么 引用 在 Hack 中 是 不 允许 的 ”。 可 变 变量 允许 “超越 作用 ”的 存在 。 它 们 允许 通 过 一 个 抽象 层 对 局 部 变量 进行 读 写 ， 而 这 个 抽象 层 对 类 型 检查 器 完全 不 透明 。 


这 里 还 有 一 个 性 能 上 的 问题 ， 当 转化 PHP 和 Hack 到 字 节 码 时 ，HHVM 为 每 个 局 部 变量 赋予 一 个 数字 编号 ， 而 这 个 数字 编号 从 0 开始 逐步 递增 。 在 运行 环境 中 ， 一 个 函数 中 的 所 有 局 部 变量 在 内 存 中 是 按 
照 数字 顺序 连续 存储 的 ， 并 且 能 够 通过 一 个 简单 的 机 器 指令 访问 每 个 局 部 变量 。 如 果 可 变 变量 没有 被 牵扯 进来 ， 在 运行 环境 中 ，HHVM 就 根本 不 需要 记 住 每 个 局 部 变量 的 名 字 ; 每 个 局 部 变量 的 使 用 都 被 它 
们 的 编号 蔡 代 ， 并 且 这 个 编号 就 是 在 内 存 中 对 其 内 容 进行 查找 的 全 部 信息 。 但 是 如 果 可 变 变 量 参与 进来 ，HHVM 就 必须 对 一 个 局 部 变量 名 和 内 存 位 置 的 mapping 进 行 维护 ， 当 进入 一 个 函数 时 就 设置 这 个 
mapping， 而 退出 这 个 函数 时 销毁 它 。 这 将 消耗 额外 的 时 间 及 内 存 。 


4.5 动态 属性 


在 PHP 中 ， 你 可 以 通过 对 一 个 对 象 的 属性 进行 赋值 ， 从 而 创建 对 象 属性 。 你 还 可 以 通过 类 似 的 方法 创建 一 个 局 部 变量 : 


<?php 


class C { 


function f(): void { 


$c = new C(); 
$c->prop = 'hi'; 
echo $c->prop; // 输 出 'hi' 


} 


或 者 


其 中 


在 Hack 中 ， 这 是 不 合法 的 ;你 必须 要 声明 所 有 的 属性 。 如 果 你 知道 一 个 对 象 的 所 有 属性 ， 那 么 声明 这 个 对 象 是 非常 有 帮助 的 。 如 果 你 不 知道 这 个 对 象 的 所 有 属性 ， 那 么 请 使 用 shape ( 见 3.3 节 的 内 容 ) 


Map (参见 第 5 章 ) 来 蔡 代 一 个 对 象 。 


这 是 为 了 类 型 安全 和 性 能 表现 。 总 的 来 说 ， 类 型 检查 器 不 可 能 推断 出 动态 属性 的 类 型 ， 甚 至 对 于 给 定 的 属性 是 否 存在 ， 它 都 无 从 得 知 。 


性 能 问题 是 : HHVM 在 内 存 中 为 一 个 对 象 已 声明 的 属性 都 保留 了 位 置 ， 可 以 通过 一 个 对 象 在 内 存 中 的 开始 位 置 ， 赤 加 一 个 已 知 的 变量 位 移 就 可 以 访问 一 个 声明 的 属性 。 在 这 过 程 中 ， 并 没有 哈 希 表 参与 


。 但 如 果 是 动态 属性 的 话 ， 就 不 能 这 么 做 了 。 这 需要 在 哈 希 表 中 存储 这 些 动态 属性 ， 而 对 动态 属性 进行 读 写 时 ， 每 一 次 都 必须 到 哈 希 表 中 进行 查找 (这 点 和 可 变 变量 的 性 能 问题 非常 相似 ) 。 


4.6 混合 方法 调用 语 ; 


在 PHP 中 ， 你 可 以 用 非 静态 方法 调用 语法 来 调用 静态 方法 ， 你 还 可 以 用 静态 方法 调用 语法 来 调用 一 个 非 静态 的 方法 : 


ClassC { 


Public function nonstaticMethod () 
Public static function staticMethod ( 


} 


C: :nonstaticMethod(); 


$c = new C(); 


$c->staticMethod (); 


但 是 上 述 这 些 在 Hack 中 都 是 非法 的 。 静 态 方法 只 可 以 用 : : 语法 来 调用 ， 而 非 静态 方法 页 只 能 够 用 - > 语法 来 调用 。 


全 于 
小 二 法 


// 在 PHP 中 是 允许 的 


// 在 PHP 中 是 允许 的 


Hack 禁 止 这 种 行为 的 主要 原因 就 是 : 如 果 一 个 非 静态 方法 用 : : 语法 调用 ， 那 么 在 这 个 方法 中 $this 对 象 是 null。 这 是 有 问题 的 。 这 里 没有 任何 理由 期 待 一 个 非 静 态 的 方法 能 够 容忍 $this 对 象 为 null。 当 


它 试 


4.7 


存在 静态 方法 和 非 静 态 方法 的 


图 去 调用 一 个 方法 或 者 访问 $this 对 象 上 的 某 个 属性 ， 会 立即 发 生 个 错误 。 如 果 这 个 方法 没有 使 用 $this 对 象 ， 那 么 从 一 开始 ， 它 就 不 应 该 是 


个 


非 静 态 方法 。 


区 别 是 有 原因 的 。 这 个 方法 正常 工作 时 是 否 需要 对 象 上 下 文 ? 在 调用 点 上 人 允许 这 种 差别 被 清除 将 导致 这 种 


表达 式 isset、empty 和 unset 在 


isset、empty 和 unset 


局 部 模式 下 是 允许 存在 的 ， 但 是 在 严格 模式 下 无 效 。 


别 无 用 ， 这 对 我 们 并 没有 任何 帮助 。 


它们 三 个 在 PHP 的 语法 和 语义 中 都 有 缺陷 。 它 们 看 起 来 和 普通 的 函数 差不多 ， 但 是 事实 并 非 如 此 。 它 们 在 PHP 的 语法 中 是 特例 ， 所 以 才 有 可 能 传递 一 个 未 定义 的 变量 和 索引 表达 式 (例如 
$nonexistent[nonexistent]) ， 而 不 引发 任何 警告 。 它 们 的 不 寻常 之 处 还 表现 于 : 在 isset 和 unset 中 ， 你 不 可 以 传递 任意 表达 式 作为 实 参 [1]。 你 只 能 传递 合法 的 左 值 表达 式 (例如 在 一 个 赋值 表达 式 中 能 


现在 


左手 边 的 表达 式 ) 。 “看 起 来 是 个 函数 但 实际 上 不 是 ”的 现象 伤害 了 语言 的 整洁 性 ， 这 也 是 和 这 些 特性 冲突 的 一 个 原 


在 Hack 中 ， 没 有 什么 理由 去 使 


是 否 被 定义 应 该 是 静态 可 知 的 。 


因 。 


isset 或 者 empty 用 来 测试 一 个 变量 是 否 被 定义 : 在 指定 的 位 置 ， 一 个 变量 : 


为 了 测试 一 个 数组 元 素 是 否 存在 ， 可 以 使 用 内 置 的 函数 array_key_exists () 来 代替 isset 或 者 empty。 不 | 


unset 则 有 些 不 同 。 在 Hack 中 ， 没 有 什么 理由 在 一 个 变量 上 使 用 它 。 如 果 你 想得到 相同 的 效果 ， 简 单 地 把 null 研 值 给 这 个 变量 即 可 。 在 PHP 中 ， 这 里 有 : 


引 


担心 性 能 


关系 。 但 是 在 Hack 中 这 没有 必要 ， 因 为 本 身 就 不 支持 引用 这 个 特性 。 


这 个 限制 唯一 可 能 产生 的 问题 就 是 你 不 能 在 严格 模式 下 移 除数 组 元 素 。 我 们 推荐 使 


来 实现 该 功能 。 


[由 直到 PHP 5.5， 这 条 限制 也 适用 于 empty。 


4.8 其 他 


在 Hack 中 不 支持 的 PHP 特 性 还 包括 : 


eval () 通 数 和 它 的 近亲 create_function () 函数 


当然 ， 这 些 函 数 的 相关 影响 是 不 可 能 静态 分 析 的。 这 样 使 


以 


持 不 


了 


普通 的 写法 代替 ) ; 或 者 足够 复杂 以 至 于 产生 重大 的 正确 性 或 者 安全 风险 。 


extract () 函数 


这 个 函数 的 使 用 ， 在 类 型 检查 器 层面 上 ， 在 任何 模式 下 ， 都 不 会 引起 什么 错误 。 然 而 ， 类 型 检查 器 不 会 追踪 它 对 局 计 


亦 
So 


gpto 语 句 


函数 通常 来 说 也 是 非常 糟糕 的 编程 实践 。 对 eval () 的 使 用 通常 不 外 了 


面 的 问题 : HHVM 对 array_key_exists () 的 调用 做 了 特别 的 优化 。 


他 的 理由 在 一 个 变量 上 使 用 unset 一 一 切断 一 个 


collection ( 详 见 第 5 章 ) 来 代替 一 个 array。 如 果 不 可 行 ， 你 可 以 在 局 部 模式 文件 下 ， 定 义 一 个 使 用 unset 的 helper 


两 种 情况 : 足够 简单 以 至 不 用 eval () 也 可 以 (这 种 情况 下 ， 代 码 可 


单 的 假设 在 extract () 函数 执行 前 后 ， 所 有 的 局 部 变量 都 保 


goto 语 句 在 程序 员 界 是 著名 的 老 争议 话题 了 ， 他 们 中 的 很 多 人 对 此 都 有 这 样 或 者 那样 的 强烈 意见 。 关 于 这 个 争议 话题 ， 我 们 这 里 没有 必要 对 其 改头换面 旧事 重 提 。 最 重要 的 事情 是 Hack 团 队 对 它 说 


no”， 所 以 Hack 并 不 支持 goto。 


break 和 continue 的 实 参 


在 Hack 中 ，break 和 continue 语 句 不 允许 引入 实 参 了 。 (在 PHP 中 ， 实 参 被 用 来 打 断 或 者 继续 多 重 府 套 循环 。 例 如 break (2) 。) 


字符 串 的 递增 和 递减 


在 Hack 中 ，++ 和 -- 操 作 符 不 能 在 字符 串 上 使 用 。 在 常规 的 PHP 中 ， 这 样 做 将 有 着 非常 有 意思 的 行为 ， 例 如 : 在 "9" 上 面 使 用 ++ 的 话 ， 我 们 可 以 得 到 "10"。 在 "a" 上 面 使 用 我 们 可 以 得 到 "b"。 应 | 
到 "z" 上 面 的 话 ， 我 们 可 以 得 到 “aa”。 这 种 行为 没有 什么 实际 的 用 途 ， 但 是 如 果 你 真 的 需要 它 ， 唯 一 的 选择 就 是 正常 地 编写 相关 代码 。 


and、or 和 xot 操 作 符 


前 两 个 我 们 可 以 分 别 使 用 && 和 || 来 代替 。 但 是 请 注意 ， 它 们 在 操作 优先 级 顺序 上 是 落 入 不 同 的 位 置 的 。 请 使 用 圆 括号 来 确保 你 的 表达 式 按 着 期 待 的 方式 进行 解析 。 而 对 于 xor 操 作 符 ， 这 里 没有 什么 蔡 
代 选 择 。 最 接近 的 选择 是 ^ 操 作 符 ， 它 实现 了 按 位 异 或 而 不 是 逻辑 异 或 ， 有 着 不 同 的 优先 级 。 


PHP 只 有 一 个 内 置 的 集合 类 型 : 数组 。 它 代表 着 一 个 接口 ， 这 个 接口 是 一 组 有 序 键 值 对 。 这 个 接口 允许 用 来 承载 不 同 的 数据 结构 ， 而 这 些 在 大 多 数 程序 中 都 较为 常见 : 向 量 、 集 合 和 映射 (或 者 称 之 为 
字典 ) 。 


Hack 有 很 多 类 用 于 提供 专门 的 向 量 、 集 合 和 了 映射 的 功能 。 它 们 对 Hack 的 类 型 检查 器 和 代码 阅读 人 员 都 有 着 更 好 的 易 懂 性 。 


ET 


在 Hack 中 一 共有 七 种 集合 类 : 


Vector 


一 个 可 变 、 有 序 的 值 ， 用 整数 进行 索引 。 索 引 是 从 0 到 n - 1 的 整数 ， 在 这 里 ，n 是 该 向 量 中 的 元 素 个 数 。 


Map 


山 
cs 


一 个 可 变 、 有 序 的 唯一 键 的 组 合 ， 每 个 键 都 映射 到 一 个 值 。 键 可 能 是 整 型 或 者 字符 串 ， 而 值 可 以 是 任何 类 型 。 不 像 其 他 编程 语言 中 的 Map 类 型 ，Hack 的 Map 记 住 它们 的 值 被 插入 的 顺序 。 相 对 于 其 他 


的 集合 类 而 言 ，Map 是 PHP 的 数组 最 为 接近 的 。 


Set 


一 个 可 变 、 有 序 的 唯一 值 的 组 合 ， 值 可 能 是 整 型 或 者 字符 中 。 


Pair 


一 个 由 两 个 值 组 成 的 不 可 变 序列 ， 由 整 型 和 1 进行 索引 。 对 于 其 他 类 而 言 ，Pair 是 API 级 别 的 细节 ， 通 常 来 说 不 应 该 自己 主动 创建 它们 。 请 使 用 tuple 来 进行 替代 (参见 1.4 节 的 内 容 ) 。 


ImmVector、ImmMap 和 ImmSet 


分 别 对 应 于 Vector、Map 还 有 Set 的 不 可 变 版 本 。 


Vector、Map、sSet、Pair 代 表 了 PHP 数 组 的 大 多 数 使 用 情况 。 


在 本 章 中 ， 我 们 将 看 到 为 什么 以 及 怎样 使 用 Hack 的 集合 类 。 


从 区 将 在 本 章 的 学 习 中 ， 使 用 明确 的 小 写 v 的 vector 和 大 写 V 的 Vector， 同 样 还 有 map、set 和 pair。 我 将 会 使 用 vectot 来 指 代 一 般 概 念 上 的 有 序 值 ， 同 其 他 编程 语言 一 样 。 然 后 我 将 使 用 Vector 来 特殊 指 代 
Hack 提 供 的 类 。 


当 我 在 本 章 中 使 用 词 array 的 时 候 ， 它 特别 意味 着 PHP/Hack 中 用 于 关键 词 array 的 数据 类 型 。 
为 什么 Map 保 留 插入 顺序 ? 
这 是 一 个 困难 的 决定 ， 背 后 的 因素 都 经 过 了 大 量 的 论证 ， 论 证 的 要 点 就 是 : 关于 软件 工程 的 用 语 问题 如 何 能 够 禾 盖 原则 。 


当 Hack 的 集合 首次 被 开发 完毕 ，Map 并 没有 保留 插入 顺序 。 如 果 一 个 工程 师 需要 保留 一 个 Map 中 的 键 顺序 ， 解 决 方案 就 是 一 个 Map 外 加 一 个 Vector， 或 者 类 似 的 其 他 组 合 。 从 一 个 语言 及 库 设 计 者 的 角度 
来 说 ， 在 Map 的 实现 中 提供 最 大 的 灵活 性 才 是 理想 的 选择 。 


然后 ， 这 里 有 两 个 因素 导致 一 个 新 类 StableMap 的 诞生 ， 它 就 是 一 个 保留 插入 顺序 的 Map。 第 一 个 因素 就 是 期 待 使 用 编程 的 方式 把 对 atrray 的 使 用 转化 为 对 collection 的 使 用 。 而 对 于 一 个 程序 来 说 ， 它 很 难 判 
断 对 于 一 个 给 定 atray 的 使 用 是 否 依赖 于 保留 插入 顺序 的 atray， 这 种 情况 下 请 使 用 StableMap。 


第 二 个 因素 就 是 相互 操作 的 能 力 。 和 其 他 Hack 特 性 一 样 ， 对 Hack 集 合 类 设计 的 首要 目标 就 是 和 已 经 存在 的 使 用 array 的 代码 能 够 容易 地 相互 操作 。 我 们 期 待 在 array 和 Map 之 间 有 大 量 的 转换 ， 如 果 Map 不 保 
留 播 入 顺序 的 话 ， 这 些 转换 将 是 有 损耗 的 。 


StableMap 和 Map 的 出 现 导 致 工程 师 们 有 个 认 知 上 的 负担 。 在 PHP 中 ， 从 来 没有 人 会 思考 “使 用 一 个 array 时 ， 是 否 需要 保留 顺序 ”， 因 为 这 里 根本 就 没有 选择 。 那 么 collection 出 现 了 ， 这 变 成 了 一 个 重要 的 
选择 。 这 里 还 有 个 API 级 别 的 摩擦 : 如 果 一 个 模块 使 用 了 Map， 而 另外 一 个 模块 使 用 StableMap， 那 么 它们 之 间 能 够 相互 沟通 吗 ? (这 里 有 一 些 像 ConstMap 和 MutableMap 接 口 可 以 用 于 平息 这 个 API 摩 擦 ， 但 是 


这 可 能 给 Hack 和 PHP 工 程 师 们 带 来 更 多 的 复杂 性 。) 


鉴于 上 述 原 因 ， 我 们 最 终 决 定 使 Map 保 留 插入 顺序 ， 并 且 删 除 StableMap。 但 是 到 处 保留 插入 顺序 对 性 能 表现 的 影响 可 能 非常 不 同 。 幸 运 的 是 ， 事 实证 明 并 非 如 此 。 在 HHVM 中 ， 我 们 能 够 从 常规 PHP 的 
atray 中 实现 应 用 消除 StableMap 和 Map 之 间 的 性 能 差距 。 


这 里 有 个 非常 有 趣 的 基于 性 能 考虑 的 微小 差别 : 在 实践 中 ， 我 们 已 经 决定 保留 Map 和 StableMap， 我 们 不 得 不 走出 我 们 的 方式 使 Map 没 有 保留 插入 顺序 ， 以 避免 人 们 依赖 这 种 行为 。 这 也 是 有 性 能 损耗 的 。 


5.1 为 什么 使 用 集合 


这 里 有 一 条 深层 次 的 原因 使 用 collection 来 代替 array: PHP 的 array 是 极其 灵活 的 。 但 在 实践 中 ， 应 用 程序 都 是 在 一 小 批 非常 具体 的 模式 下 使 用 的 : vector、map 和 set。 正 确 使 用 集合 类 型 将 可 以 使 人 
类 和 计算 机 的 世界 都 变 得 更 加 美好 。 


对 于 代码 的 阅读 者 来 说 ， 看 到 具体 的 集合 名 将 使 它们 的 目的 更 加 清晰 。 当 和 Hack 的 类 型 标注 相 结合 时 ， 这 些 好 处 就 会 变 得 更 加 具有 说 服 力 : 当 一 个 集合 通过 每 个 抽象 边界 的 时 候 ， 使 用 它 的 目的 将 非常 
清晰 。 这 将 减少 错误 发 生 的 概率 ， 并 且 使 开发 更 快 更 简单 。 


| 


对 计算 机 而 言 ， 一 个 集合 的 功能 集 越 少 ， 就 越 容易 理解 相关 的 周边 代码 。 数 组 对 于 Hack 类 型 检查 器 来 说 是 非常 难于 理解 的 ， 因 为 它 能 够 在 如 此 大 范围 内 被 人 使用。 例如， 如 果 你 正在 把 一 个 array 作 为 
vector 使 用 ， 并 把 它 传 递 给 一 个 期 待 类 map 数 组 作 函 数 的 参数 ， 这 里 将 会 有 个 类 型 错误 ， 但 是 类 型 检查 器 不 能 够 分 辩 什 么 时 候 会 发 生 : 一 般 来 说 ,分 辨 一 个 array 如 何 被 使 用 是 不 可 能 的 。 


Hack 逐 步 增加 了 这 个 问题 的 解决 方案 ，shape ( 详 见 3.3 节 的 详细 内 容 ) 就 是 这 种 效果 的 一 部 分 ， 但 是 集合 提供 了 紧急 救援 方案 。 


使 用 一 个 具体 的 集合 类 也 有 性 能 方面 的 好 处 。 作 为 一 个 例子 ，array 通 常会 申请 比 它 实际 需要 更 多 的 内 存 空 间 ， 所 以 当 一 个 值 被 添加 的 时 候 ， 就 不 需要 每 一 次 都 申请 内 存 分 配 了 。 然 而 ， 一 些 数组 从 来 不 
会 被 修改 ， 所 以 这 个 额外 的 容量 被 浪费 掉 了 ; 与 此 同时 ， 对 于 一 个 程序 员 来 说， 这 里 没有 什么 途径 表达 一 个 array 是 不 可 改变 的 。Hack 的 集合 类 就 有 这 个 特性 。 


更 高 层次 使 用 集合 的 原因 非常 简单 ， 因 为 集合 的 存在 和 Hack 更 加 亲近 静态 类 型 的 哲学 逻辑 更 搭配 。 对 于 人 和 计算 机 而 言 ， 通 过 静态 类 型 表达 一 个 程序 行为 越 多 越 好 。 集 合 就 是 这 样 一 个 广 范围 、 高 附加 
值 的 选择 。 


5.2 ”集合 拥有 引用 语义 


如 果 你 从 一 开始 就 用 Hack 编 写 一 个 项 目的 代码 ， 那 么 当 你 需要 集合 功能 的 时 候 ， 基 于 先前 文章 里 面 提 到 的 原因 ，Hack 的 集合 类 将 是 你 的 首要 选择 。 


如 果 你 正在 一 个 有 着 大 量 已 经 存在 的 PHP 代 码 的 环境 下 工作 ， 试 图 使 用 集合 类 替代 数组 将 会 是 非常 大 的 挑战 。 原 因 就 是 在 array 和 collection 之 间 的 一 个 主要 语义 差异 : array 有 着 值 语义 ， 而 collection 
拥有 引用 语义 。 


这 个 问题 两 个 可 能 的 答案 将 代表 这 两 种 概念 : 在 下 面 的 例子 中 ， 最 后 一 条 语句 会 输出 'original 还 是 new'? 


$var one = array('original'); 
Svar two = $var one; 

$var two[0] = 'new'; 

echo $var_one [0T; 


答案 是 'original'， 这 与 值 语义 一 致 。 当 你 把 数组 赋值 给 了 $var two 的 时 候 ， 这 个 数组 被 复制 了 [0， 所 以 对 $var_ two 的 更 改 并 不 会 影响 $var_one (反之 亦 然 ) 。 


集合 则 站 在 了 相反 的 方面 。 它 们 用 于 引用 语义 ， 就 像 Hack 和 PHP 中 所 有 的 对 象 一 样 。 如 果 我 们 例子 中 的 $var_one 用 一 个 Vector 代替 ， 最 后 一 条 语句 将 输出 "new'。'$var two=$var_one 的 赋值 并 不 会 
复制 Vector， 所 以 对 $var_ two 的 修改 将 会 对 $var_one 造 成 影响 。 


这 似乎 是 个 相当 小 的 差异 ， 如 果 你 正在 使 用 collection 的 代码 代替 数组 的 代码 ， 那 么 你 需要 意识 到 这 是 有 深远 影响 的 。 在 典型 的 代码 中 ， 对 数组 的 伪 复 制 (正如 前 例 所 示 ) 是 无 处 不 在 的 ， 它 在 你 传递 一 
个 数组 到 一 个 函数 ， 或 者 从 一 个 函数 返回 一 个 数组 的 任何 时 刻 都 会 发 生 。 


这 里 有 个 情况 的 例子 ， 在 这 里 你 需要 思考 这 个 不 同 之 处 : 


function get items(): array<string> { 
static $cache = null; 
if ($cache === null) { 
$cache = do_expensive fetch(); 


} 


return $cache; 


function main(): void { 
$items = get items(); 
$items[] = some_special item(); 


foreach ($items as Sitem) { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 
} 


main () 在 修改 从 函数 get_items () 得 到 的 返回 值 时 ， 它 缓存 了 do_expensive_fetch () 函数 的 结果 到 一 个 静态 局 部 变量 。 因 为 get_items () 函数 返回 了 一 个 数组 ， 所 以 这 个 代码 是 正确 的 : 
main () 作用 于 一 个 独立 的 数组 拷贝 ， 它 来 自 于 一 个 在 get_items () 函数 中 存储 的 静态 变量 。 


然而 ， 如 果 这 段 代 码 被 机 械 地 转换 为 使 用 collection， 以 便 do_expensive fetch () 和 get items () 返回 Vector<string> 作 为 替代 ， 这 段 代码 将 被 打 断 。Vector 从 来 没有 被 复制 ， 所 以 main () 对 


Vector 的 修改 将 不 会 对 任何 get_items () 函数 的 调用 者 可 见 。 


请 注意 ， 这 是 一 个 关于 memoization 的 例子 。 当 使 用 特殊 的 属性 _Memoize 的 时 候 ， 你 也 需要 注意 这 个 问题 (参见 3.6.2 节 的 相关 内 容 ) 。 


抵御 这 个 问题 的 第 一 道 防线 就 是 不 变性 。get_items () 函数 应 该 返回 一 个 不 变 的 Vector， 这 个 核心 要 领 就 是 调用 者 不 应 该 改变 它 。 如 果 它 们 需要 改变 ， 那 么 应 该 复制 一 份 ， 然 后 对 拷贝 进行 修改 (这 
就 是 在 基于 array 的 代码 中 隐 式 发 生 的 事情 ) 。 


这 里 是 get_items () 函数 如 何 利用 collection 来 实现 的 方式 (在 5.4 节 中 ， 我 们 将 看 到 ConstVector 变 量 标注 的 相关 含义 ) : 


function get items(): ConstVector<string> { 
static $cache = null; 
if ($cache === null) { 
$cache = do _ expensive fetch(); 
} 
return $cache->immutable(); 


} 


每 个 集合 类 都 有 一 个 方法 名 叫做 immutable () ， 它 返回 一 个 它 自己 的 不 可 变 版 本 。 这 个 并 非 复 制 集合 在 内 存 中 的 基础 存储 。 事 实 上 它 很 轻 量 ， 因 为 它 和 PHP 数 组 的 写 时 复制 非常 类 似 。 这 种 情况 下 ， 
如 果 get items () 的 任何 调用 者 试图 修改 它 返 回 的 Vector， 一 个 “非法 操作 异常 (InvalidOperationException) ”将 会 被 抛 出 ， 非 常 清晰 地 向 你 展示 什么 需要 被 修改 。 


[由 在 这 一 点 上 ， 不 管 是 标准 的 PHP 还 是 HHVM， 内 存 中 它 并 不 真正 进行 复制 。 相 反 ， 它 仅仅 在 被 修改 时 ， 才 进行 复制 。 这 个 就 叫做 “ 写 时 复制 ”。 你 可 能 听 说 过 “PHP 数 组 是 写 时 复制 ”的 论断 ， 这 是 真实 
的 。 但 描述 为 一 种 实现 而 不 是 一 种 语义 更 为 合适 。 好 吧 ， 可 以 这 么 说 。 写 时 复制 应 该 是 一 种 细节 上 的 实现 ， 它 表现 上 看 起 来 是 当 赋 值 发 生 时 数组 被 复制 ， 但 这 并 不 完全 。 这 里 有 一 些 非常 规 的 例子 可 以 证 明 


写 时 复制 是 可 以 被 察 党 的， 然而 这 些 例 子 在 语言 中 都 是 些 有 争议 的 bug。 


5.3 ”使 用 集合 


在 HHVM， 集 合 类 甚至 可 以 在 常规 的 PHP 文 件 中 进行 使 用 ( 换 名 话说， 就 是 非 Hack 文 件 ) 。 你 必须 在 这 些 类 名 前 面 使 用 HH 的 命名 空间 前 缀 《例如 HH/Vector) ， 然 而 在 Hack 文 件 中 ， 这 些 命名 空间 并 
非 必需 。 


使 用 集合 的 代码 看 起 来 和 使 用 数组 的 代码 几乎 一 样 。 集 合 在 语言 和 运行 环境 中 都 是 内 置 的 ， 所 以 它们 可 以 和 许多 已 经 在 数组 中 使 用 的 语言 结构 体 无 颖 地 对 接 工 作 。 我 们 将 在 本 节 中 对 它们 一 一 学 习 。 每 
个 集合 类 都 有 一 个 功能 齐全 的 面向 对 象 的 接口 ， 我 们 在 这 里 (在 5.4 节 ) 将 会 看 到 其 中 最 重要 的 部 分 。 


5.3.1 ”字面 量 语 ; 


Hack 对 创建 一 个 集合 类 实例 添加 了 特殊 的 语法 ， 我 们 称 之 为 集合 字面 量 语法 。 它 包括 类 名 ， 紧 随 其 后 的 是 大 括号 括 起 来 的 项 目 列表 。 这 些 项 目 用 逗号 进行 分 隔 。 在 Map 字 面 量 中 ， 每 个 项 目 都 是 一 个 
键 ， 紧 跟着 = > ， 然 后 是 值 ， 这 和 PHP 数 组 的 字面 量 语法 是 一 致 的 : 


S$vector = Vector {'one', 'two', 'three'}; 
Smap = Map {'one' => 1, 'two' => 2, 'three' => 3}; 
$set = Set {'one', 'two', 'three'}; 


$pair = Pair {'one', 'two'}; 


合 字面 量 语法 和 常规 PHP 的 array () 语法 允许 出 现 的 位 置 是 一 样 的 ， 包 括 对 象 的 初始 化 表达 式 和 类 属性 。 它 存在 的 原因 是 : 即使 集合 字面 量 语法 需要 对 象 的 创建 (通常 在 这 些 位 置 上 是 不 允许 的 ) ， 
但 array () 合法 的 任何 地 方 ， 它 就 是 合法 的 。 例 如 : 


class Pluralizer { 
private static Map<string, string> $cache = Map {}; 


集合 字面 量 的 这 个 位 置 不 允许 包含 “ 它 自己 在 该 位 置 所 不 允许 ”的 任何 表达 式 。array() 语法 有 相同 的 限制 。 例 如 ， 这 里 不 合法 的 语法 是 因为 函数 调用 是 不 合法 类 属性 的 初始 化 者 : 


class Pluralizer { 
// 语法 错误 
private static Map<string, string> $cache = 
Map {'child' => fetch plural from db('child')}; 


值得 注意 的 是 ， 虽 然 集合 类 是 基本 的 类 型 ， 但 是 它们 在 字面 量 语法 中 没有 任何 类 型 的 实 参 : 


$vec = Vector<int> {1, 2, 3}; // 语 法 错误 


相反 ， 类 型 检查 器 将 会 静默 地 对 集合 内 的 内 容 类 型 进行 跟踪 ， 仅 当 它 通过 一 个 类 型 标注 进行 传递 的 时 候 ， 才 进行 错误 检查 (比如 把 它 作为 类 型 标注 赋值 给 一 个 属性 ) 。 详 见 2.5 节 的 相关 内 容 。 


5.3.2 ” 读 和 写 


使 用 array 时 所 用 的 方 括 号 语法 同样 适用 于 Vector、Map 和 Pair: 


$vector = Vector {'zero', 'one', 'two'}; 
echo $vector[1]; // 输出 "one' 


Smap = Map {1}; 
$map['zero'] = 0; 


$pair = Pair {'first', 'second'}; 
echo Spair[0]; // 输出 'first' 


如 果 你 试图 读 取 一 个 不 存在 的 元 素 ， 或 者 对 一 个 Vector 边界 之 外 的 元 素 进行 设置 的 话 ， 类 型 检查 器 将 会 抛 出 一 个 “越界 异常 (OutOfBoundsException) ”。 通 过 引用 对 元 素 进 行 访问 的 方法 (就 像 在 


常规 PHP 中 ，$ref=&$array[0]) 在 集合 这 边 是 行 不 通 的 。 这 样 做 的 结果 只 会 得 到 一 个 致命 错误 提示 。 


而 对 于 Set， 你 不 应 该 使 用 这 个 方 括号 语法 去 修改 。 你 可 以 使 用 它 去 读 取 Set 中 的 值 ， 但 是 你 不 应 该 这 么 做 。 对 于 一 个 Set 最 常见 的 操作 就 是 检测 一 个 值 是 否 包含 在 Set 中， 而 方 括号 语法 对 其 并 不 合适 : 
如 果 一 个 值 不 包含 在 set 里 面 ， 它 将 会 抽出 一 个 “越界 异常 ”错误 。 为 了 成 员 关系 测试 的 目的 ， 请 使 用 contains () 方法 ( 见 5.4 节 的 相关 内 容 ) 进行 替代 。 


if (Sthe 1ist->contains (Suser id)) { 
echo "You're on the list"; 


} 


array 有 个 古怪 的 行为 ， 如 果 其 中 字符 串 的 键 可 以 表述 为 一 个 整 型 ( 注 : 这 和 “把 一 个 字符 串 转化 为 整 型 ”事实 上 还 不 是 相同 的 逻辑 。 这 个 字符 串 必须 是 在 - 263 到 263 - 1 之 间 的 一 个 整数 ， 没 有 前 置 或 
尾随 的 空白 字符 ， 也 没有 前 置 的 数字 零 。 这 个 “特性 ”在 性 能 表现 上 非常 糟糕 : 数组 查找 在 任何 PHP 或 者 Hack 程 序 中 都 是 非常 常见 的 操作 。 而 在 每 一 次 数组 查找 的 时 候 ， 键 都 必须 被 上 述 条 件 检查 。 这 里 有 
一 些 可 能 的 小 优化 ， 但 这 里 仍然 是 个 值得 注意 的 性 能 损耗 。) ， 就 会 被 当 作 整 型 进行 替换 。 例 如 : 


$array = array('3' => 'three'); 
echo $array[3]; // 输出 'three' 
$array = array(3 => 'three'); 
echo $array['3']; // 输出 'three' 


Hack 的 集合 并 不 这 样 做 。Map 和 Set 将 字符 串 "3" 和 整 型 3 视 为 不 同 键 ， 同 时 如 果 你 对 Vector 和 Pair 使 用 非 整 型 作为 索引 ， 将 会 抛 出 一 个 “非法 参数 异常 (InvalidArgumentException) ”。 


如 果 要 测试 Map 中 是 否 存 在 键 ， 或 者 测试 Set 中 是 否 存在 一 个 元 素 ， 你 可 以 分 别 使 用 containsKey () 方法 和 contains () 方法 : 


Smap = Map {'one' => 'un', 'two' => 'deux'}; 


if ($map->containsKey('two')) { 
echo "We know how to say 'two' in French!"; 


$set = Set {'one', 'two'}; 
if ($set->contains('one')) { 
echo "'one' is in the set"; 


} 


当然 ， 你 还 可 以 使 用 isset 或 者 empty 检 测 一 个 键 或 者 元 素 是 否 存在 ， 但 是 应 该 尽量 使 用 containKey () 或 者 contains () 。isset 和 empty 在 Hack 的 严格 模式 下 是 不 允许 的 ， 如 果 想 知道 详细 原因 ， 可 
以 参见 4.7 节 的 相关 内 容 。 你 对 集合 想 使 用 它们 (isset、empty、unset) 的 唯一 原因 就 是 ， 你 可 以 写 出 对 于 array 和 和 集合 都 无 颖 对 接 的 代码 。 


就 像 空 的 数组 一 样 ， 当 任何 类 型 空 的 集合 被 转化 为 布尔 型 时 ， 都 等 于 false。 在 具体 实践 中 ， 它 们 在 条 件 语句 中 被 当 作 false 对 待 ， 比 如 f、while 以 及 三 元 表达 式 : 


$vector = Vector {}; 
if ($vector) { 


// 这 里 的 代码 未 被 执行 
} 


$description = ($vector ? (string) Svector : '[none] '); 
和 迭代 
$vector = Vector {'zero', 'one'}; 


foreach ($vector as $value) { 
echo $value; 
} 


Smap = Map {'one' => 'un', 'two' => 'deux'}; 
foreach ($map as $eng => $fr) { 
echo $eng . ' in French is ' . $fr; 


} 


当 对 其 进行 迭代 的 时 候 ， 在 一 个 集合 上 面 增加 或 者 删除 一 个 项 目 是 不 允许 的 。 结 果 会 得 到 一 个 “非法 操作 异常 (InvalidOperationException) ”。 


像 在 foreach ($vector as &$value) 中 对 引用 进行 迭代 也 是 不 允许 的 。 结 果 会 导致 一 个 致命 错误 。 你 可 以 通过 添加 一 个 键 或 者 索引 作为 一 个 迭代 变量 ， 来 进行 类 似 行 为 的 操作 ， 例 如 
foreach ($vector as$index= >$value) 语句 所 示 ， 然 后 通过 这 样 的 办 法 修改 里 面 的 值 : 


// 使 用 数组 的 老 代 码 

$array = array(0, 1, 2); 

foreach ($array as &$value) { 
$value *= 10; 


} 
// 使 用 Vector 的 等 价 代码 


$vector = Vector {0, 1, 2}; 
foreach ($vector as $index => $value) { 
$vector[$index] = $value * 10; 


添加 值 


你 可 以 使 用 正常 的 空 方 括 号 语法 ， 对 Vector 添 加 一 个 值 ， 还 可 以 添加 它们 到 Set 中 。 在 Set 的 情况 下 ， 如 果 对 应 的 值 在 Set 中 已 经 存在 了 ， 这 不 会 有 任何 影响 : 


$vector = Vector {'zero'}; 


$vector[] = 'one 


print r ($vector); // 输出 : "HH\Vector Object( [0] => zero, [1] => one )" 


$set = Set {'eins'}; 
$set[] = 'eins'; // $set 中 己 经 存在 这 个 值 ， 什 么 都 不 会 发 生 
print r($set); // 输出 : "HH\Set Object( eins )" 


同样 的 语法 对 于 Map 也 是 生效 的 ， 但 因为 你 必须 指明 一 个 键 和 一 个 值 ， 所 以 表达 式 右手 边 必须 是 个 键 和 值 的 键 值 对 : 


Smap = Map {1}; 
Smap[] = Pair {'one', 'eins'}; 
print r($map) // 输出 : "HH\Map Object( [one] => eins )" 


你 还 可 以 在 Vector 和 Set 上 面 使 用 add () 方法 ， 把 要 添加 的 值 当成 唯一 的 实 参 进 行 传递 。Map 也 有 add () 方法 ， 请 传递 给 它 一 个 Pair 的 键 和 值 。 


删除 值 


如 果 想 从 Vector 中 删除 一 个 值 ， 那 么 请 使 用 removeKey () 方法 : 


$vec = Vector {'first', 'second', 'third'}; 
$vec->removeKey (1); 
print r($vec); // 输出 : "HH\Vector Object( [0] => first, [1] => third )" 


值得 注意 的 是 ， 被 删除 元 素 后 面 的 元 素 都 将 会 向 下 移动 一 个 索引 ， 所 以 1 号 索引 前 映射 的 值 是 'third'。 这 是 符合 vector 语 义 的 ， 它 的 相关 描述 为 包含 从 0 到 n - 1 之 间 的 各 项 索引 都 是 合法 的 (这 里 面 的 n 指 
的 是 vector 中 的 元 素数 量 ) 。 


从 Map 中 删除 一 个 键 的 方法 也 叫做 removeKey () 。 如 果 从 一 个 Set 中 删除 一 个 值 ， 那 么 请 使 用 remove () 方法 。 


你 还 可 以 使 用 unset 语 句 从 Map 和 Set 中 删除 对 象 。 


Smap = Map {'one' => 'un', 'two' => 'deux'}; 
unset ($map['one']); 
print r($map); // 输出 : "HH\Map Object( [two] => deux )" 


再 次 强调 一 点 的 是 ， 你 最 好 坚持 使 用 相关 的 替代 方法 而 不 要 使 用 unset， 因 为 unset 在 严格 模式 下 并 不 能 使 用 。 如 果 你 需要 写 能 够 无 颖 地 接收 array 和 collection 的 代码 ， 你 可 以 使 用 unset。 


unset 对 于 Vector 是 无 效 的 。 这 是 因为 从 Vector 中 删除 一 个 元 素 的 语义 ， 和 从 array 中 删除 一 个 元 素 的 语义 并 不 匹配 。 对 一 个 array (即使 是 在 使 用 中 非常 接近 一 个 vector) 中 的 元 素 进行 unset 将 留 下 一 
个 “ 洞 (hole) ”， 在 这 个 地 方 ，array 的 合法 索引 将 会 是 不 连续 的 ， 所 以 这 打破 了 vector 的 语义 : 


$arr = array('zero', 'one', ‘two'); 
unset ($arr[1]); 
print r($arr); // 输出 : "Array( [0] => zero, [2] => two )" 


操作 符 


collection 可 以 使 用 = = 操作 符 进行 比较 。 这 里 是 它 的 工作 原理 : 


1. 如 果 两 边 都 不 是 同样 种 类 的 collection (不 考虑 可 变性 ) ， 结 果 将 是 false。 例 如 ，Vector 可 能 和 ImmVector 相 等 ， 但 是 它 肯定 不 等 于 Map。 


2. 如 果 两 边 是 Vector 或 者 ImmVector， 那 么 当 且 仅 当 两 边 都 含有 相同 数量 的 值 ， 并 且 每 个 对 应 索引 上 的 值 用 = = 比较 都 相等 时 ， 返 回 true。 例 如 : 


$vector = Vector {1, 2}; 

$immvector = ImmVector {1, 2}; 
$strings = Vector {'1', '2'}; 
S$wrong_order = Vector {2, 1}; 


var_dump ($vector 一 $immvector);// true 
var_ dump ($vector 一 $strings); // true, 因为 1 == '1', 2 == '2' 
var dump ($vector 一 $wrong order);// false 


3. 如 果 两 边 都 是 Pair 的 话 ， 当 且 仅 当 每 个 索引 上 的 值 用 = = 进行 比较 都 相等 时 ， 返 回 true。 


4. 如 果 两 个 都 是 Set 或 者 Immset， 那 么 当 且 仅 当 两 边 包含 相同 数量 的 值 ， 并 且 在 一 边 存 在 的 每 个 元 素 在 另外 一 边 也 存在 ， 返 回 true。 并 不 像 Vector， 它 们 的 存在 测试 都 是 使 用 = = = 恒等式 进行 比较 的 。 


在 set 比较 中 顺序 是 无 关 的 。 请 看 下 面 的 例子 : 


$set = Set {1, 2}; 
$immset = ImmSet {1, 2}; 
$strings = Set {'1', '2'}; 
S$wrong_ order = Set {2, 1}; 


var_dump ($set 一 $immset); // true 
Var dump ($set 一 $strings); // false 
var_dump ($set 一 S$wrong order); // true 


5. 如 果 两 边 是 Map 或 者 ImmMap， 那 么 当 且 仅 当下 列 情况 下 返回 true。 两 边 都 含有 相同 数量 的 键 ， 并 且 一 边 的 每 个 键 在 另外 一 边 都 存在 (使 用 恒等式 ) ， 相 同 的 键 都 映射 着 相同 的 值 ( 使 用 == 比 


较 ) ， 顺 序 是 无 关 的 。 例 如 : 


Smap = Map {10 => 20, 20 => 40}; 
$string keys = Map {'10' => 20, '20' => 40}; 
$string values = Map {10 => '20', 20 => '40'}; 


var _ dump (Smap 一 $string keys); // false 
var dump (Smap 一 $string values); // true 


collection 还 可 以 使 用 === 操 作 符 进行 恒 等 比较 。 仅 当 操作 符 两 边 都 为 相同 的 对 象 的 时 候 ， 才 会 执行 为 true。 如 果 它 们 是 不 同 的 对 象 ， 即 使 两 个 对 象 都 含有 相同 的 内 容 ，= = = 比较 也 会 返回 false: 


$vector = Vector {1, 2}; 
$another variable = $vector; 
Var_dump ($vector =—= $another variable); // true 


S$other = Vector {1, 2}; 
Var_dump ($vector === $other); // false 


对 右手 边 的 collection 进 行 list 赋 值 操作 ， 我 们 可 以 把 collection 理 解 为 array， 最 终 得 到 的 效果 是 一 样 的 。list 赋 值 是 “对 右手 边 的 array 或 者 collection 用 整 型 键 进 行 索 引 取 值 ， 然 后 赋值 ”操作 的 简要 写 


法 ， 所 以 这 种 行为 适用 于 Map 和 Set (Map 和 Set 的 内 部 顺序 并 不 影响 ) : 


$vector = Vector {'one', 'two'}; 
list($one, $two) = $vector; 


Smap = Map {1 => 'one', 0 => 'zero'}; 
list($zero，S$one) = $map; // $zero 是 'zero' 且 $one 是 'one' 


不 可 变 集合 


Vector、Map 以 及 Set 都 分 别 有 其 不 可 变 的 等 价 版 本 : ImmVector、ImmMap 和 ImmSet。 (Pair 本 身 就 是 不 可 变 的 ， 它 没有 可 变 的 情况 。) 它们 不 实现 任何 可 以 修改 它们 内 容 的 方法 ， 并 且 它 人 


门 也 不 


能 通过 方 括号 语法 或 者 unset 进 行 修改 。 如 果 你 试图 这 样 做 ， 将 会 抛 出 一 个 “非法 操作 异常 (InvalidOperationException) ”。 不 可 变 集合 的 内 容 在 它们 被 创建 的 时 候 就 固定 下 来 。 它 们 可 以 通过 字 


对 


放 


法 进行 创建 ， 仅 使 用 mmyVector、ImmMap 或 者 ImmsSet 作 为 类 名 ， 或 者 通过 它们 的 构造 器 ， 或 者 从 另外 的 collection 进 行 转换 (参见 5.4.4 节 的 相关 内 容 ) 。 


通常 来 说 ， 如 果 可 能 的 话 你 应 该 尽量 使 用 不 可 变 集合 。 如 果 一 些 数据 不 应 被 修改 ， 那 么 使 用 不 可 变 集合 就 可 以 减少 一 个 可 能 的 bug 来 源 。 在 类 型 系统 中 ， 它 还 会 对 程序 行为 编码 更 多 的 信息 ， 这 总 是 一 


件 好 事情 。 


5.4 “集合 类 型 标 ; 


大 多 数 时 间 下 ， 你 不 应 该 在 类 型 标注 中 直接 使 用 集合 类 名 称 本 身 。Hack 提 供 了 一 系列 接口 用 于 描述 集合 功能 的 元 素 ， 所 以 你 应 该 在 日 常 类 型 标注 的 时 候 使 用 这 些 接口 。 


例如 ， 如 果 你 正在 编写 一 个 函数 ， 这 个 函数 取 一 组 值 作 为 实 参 ， 并 且 不 对 它们 进行 修改 ， 那 么 相 比较 Set 而 言 ， 你 更 应 该 标注 这 个 实 参 为 ConstSet。 它 是 一 个 接口 ， 一 个 可 继承 的 实体 类 。 这 增强 了 表 


现 力 ， 可 以 帮助 类 型 检查 器 捕获 更 多 的 错误 : 如 果 你 试图 对 函数 中 的 这 个 Set 进 行 修改 ， 将 会 有 个 类 型 错误 。 这 同时 使 得 函数 定义 对 调用 者 更 加 清晰 : 它 需要 一 个 集合 ， 并 且 不 会 修改 。 


在 本 节 的 学 习 中 ， 你 将 看 到 最 有 可 能 使 用 的 接口 。 这 将 是 以 非常 自然 的 方式 来 展示 集合 类 的 面 对 对 象 接 口 。 如 果 你 只 是 想 集 中 地 查看 集合 类 的 AP1， 那 么 可 以 直接 跳 到 5.4.4 节 。 那 一 小 节 没有 对 方法 的 


解释 信息 ， 但 是 它们 中 的 大 多 数 都 可 以 从 字面 意思 上 理解 它 的 功能 ， 特 别 是 那些 类 型 标注 。 


5.4.1 核心 接口 


集合 的 核心 接口 有 : 


Traversable<T> 


任何 能 够 使 用 “不 使 用 键 的 foreach” 进 行进 代 的 都 是 Traversable。 在 这 样 的 foreach 循 环 中 ， 迭 代 变 量 的 类 型 为 T。 这 是 Traversable 唯 一 能 保证 的 事情 ， 它 并 没有 声明 任何 方法 。 


Traversable 最 重要 的 事情 是 : 常规 的 PHP 数 组 是 Traversable 的 。 这 有 些 


号 
团 


为 通常 来 说 只 有 对 象 可 以 实现 接口 ， 


作为 array 和 collection 的 补充 ，Traversable 包 含 实现 lterator 的 对 象 。 


但 array 并 不 是 对 象 。 对 于 这 种 行为 ，Traversable 在 运行 环境 中 是 个 特例 。 


Traversable 能 够 帮助 弥补 array 和 collection 之 间 的 差距 。 如 果 你 对 一 个 函数 的 实 参 (不 管 是 一 个 array， 还 是 一 个 collection， 或 者 其 他 ) 唯一 要 做 的 事情 就 是 以 不 使 用 key 的 foreach 进 行 迭代 ， 你 可 以 


考虑 把 它 标注 为 Traversable。 


值得 注意 的 是 ， 如 果 你 想 实 现 一 个 自己 的 类 ， 可 以 在 代码 编程 时 使 用 foreach 的 类 ， 你 不 应 该 让 它 实现 Traversable。 请 使 用 lterable 作 为 蔡 代 ( 稍 后 将 进行 描述 ) 。 


KeyedTraversable<Tk, Tv>extends Traversable<Tv> 


KeyedTraversable 和 Traversable 很 类 似 ， 但 是 它 特别 指明 了 在 foreach 语 句 中 包含 一 个 key 是 合法 的 。 常 规 PHP 的 数组 就 是 KeyedTraversable。 接 下 来 的 示例 将 向 我 们 展示 Traversable 和 


KeyedTraversable 的 区 别 : 


function notKeyed (Traversable<T> $traversable): void { 
// 不 合法 
foreach ($traversable as $key => $value) { 


// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


} 
} 


function keyed (KeyedTraversable<Tk, Tv> $traversable): void { 
// 合法 
foreach (Straversable as $key => $value) { 
// $key 的 类 型 是 Tk 
// $value 的 类 型 是 Tv 
} 
} 


Container<T>extends Traversable<T> 


Container 和 Traversable 非 常 相似 ， 但 是 它 并 不 包含 实现 lterator 的 对 象 。 换 句 话说 ， 它 只 包含 数组 和 集合 类 实例 。 


~ 


KeyedContainer<Tk, Tv>extends KeyedTraversable<Tk, Tv> 


KeyedContainer 和 KeyedTraversable 类 似 ， 但 是 KeyedContainer 被 限制 到 数组 和 集合 类 ， 而 不 是 Set 和 Immset。 


Indexish<Tk, Tv>extends KeyedTraversable<Tk, Tv> 


尔 使 用 Container 唯 一 能 做 的 事情 就 是 以 foreach 进 行 迭 代 。 


Indexish 表 示 能 够 使 用 方 括号 语法 进行 索引 的 任何 变量 $indexish[$key]。 它 没有 声明 任何 方法 。 就 像 Traversable 和 KeyedTraversable 一 样 ， 它 是 一 个 特殊 的 接口 ， 被 数组 、 集 合 和 其 他 支持 此 语法 的 


对 象 “实现 ”的 接口 。 


IteratorAggregate<T>extends Traversable<T> 


这 个 接口 是 为 了 一 些 对 象 而 存在 的 。 这 些 对 象 都 能 够 产生 一 个 lterator 对 象 ， 用 于 它们 的 内 容 迭 代 。 和 前 边 的 三 种 接口 


lteratorAggregate，lterable 或 者 Traversable 可 能 是 更 合适 的 选择 。|teratorAggregate 接 口 声明 了 一 个 单独 的 方法 : 


“getIterator () : Iterator<T> 将 返回 一 个 在 对 象 内 容 上 的 Tterator。 这 个 Iterator 接 口 就 是 标准 PHP 中 的 那个 接口 。 


Iterable<T>extends IteratorAggregate<T> 


这 里 才 是 集合 真正 展示 能 力 的 地 方 。lterable 接 口 声明 了 很 多 方法 : 


“ toArray () : array 把 集合 转化 为 数组 。 注 意 返回 值 并 没有 类 型 实 参 ， 这 仅仅 是 个 简单 的 array 而 不 是 attay<T>。 


“ toValuesArray () : array， 把 集合 转化 为 丢弃 key 的 数组 ， 把 对 应 的 key 依 次 用 从 0 到 n 一 1 的 整数 代替 。 


不 同 的 是 ， 它 并 没有 被 array 实 现 。 在 变量 标注 中 ， 你 也 不 可 能 使 


“ toVector () : Vector<T> ， 转 化 集合 到 一 个 Vector。 这 和 toValuesArray () 非常 相似 ; 如 果 对 应 的 集合 有 key 存 在 (例如 这 个 集合 是 个 Map) ， 这 些 key 将 会 被 丢弃 。 


' toImmVector () : ImmVector<T> ， 转 化 为 一 个 不 可 变 Vector。 
“ toSet () : Set<T> ， 把 集合 转化 为 一 个 Set， 丢 弃 所 有 可 能 存在 的 key。 
“toImmSet () : ImmSet<T> ， 转 化 为 一 个 不 可 变 的 Set。 


' values () : Iterable<T>， 返 回 Iterable 对 象 。 它 产生 自 集合 的 值 (舍弃 了 键 ) 。 


“map<Tm> (function (T) : Tm$callback) : Iterable<Tm>， 把 一 个 集合 传 入 指定 函数 后 ， 经 函数 处 理 后 的 集合 值 组 成 Iterable 对 象 进行 返回 。 这 和 标准 PHP 中 atray_map () 函数 非常 类 似 。 这 里 有 个 把 


一 个 Vector 的 元 素 对 象 都 乘 以 10 的 例子 : 


$nums = Vector {1, 2, 3}; 
print r ($nums->map (function ($x) { return $x * 10; })); 


HH\Vector Object 
( 
[0] => 10 
[1] => 20 
[2] => 30 


* filter (function (T) : bool$callback) : Iterable<T> ， 将 一 个 集合 传递 进入 一 个 给 定 函 数 ， 所 有 可 以 使 该 函数 返回 为 true 的 对 应 集合 的 value 将 组 成 用 于 返回 值 的 Iterable 对 象 。 这 里 有 个 例子 可 以 从 一 个 


Vector 中 选 出 所 有 的 偶数 : 


Snums = Vector {1, 2, 3, 4}; 
print r($nums->filter (function($x) { return $x % 2 === 0; })); 


HH\Vector Object 
( 

[0] => 2 

[1] => 4 


* Zip<Tz> (Traversable<Tz>$traversable) : Iterable<Paitr<T，Tz>> 将 返回 一 个 Iterable 对 象 ， 它 将 “该 集合 collection 中 的 value” 和 “来 自传 入 的 Traversable 的 value” 配 对 。 下 面 的 例子 是 对 这 个 函数 进行 解 


释 的 最 好 方法 : 


$english = Vector {'one', 'two', 
$french = Vector {'un', 'deux', 
print r ($english->zip ($french)); 


'three'}; 
trois'}y 


这 将 会 输出 : 


HH\Vector Object 
( 


[0] => HH\Pair Object 
( 
0] => one 
1] => un 
) 
[1] => HH\Pair Object 
( 
0] => two 
1] => deux 
) 
[2] => HH\Pair Object 
( 
0] => three 
1] => trois 


如 果 两 个 集合 有 着 不 同 的 成 员 计数 值 ， 那 么 所 得 到 的 lterable 将 会 和 更 小 的 计数 值 一 致 。 


KeyedIterable<Tk ，Tv>extends Iterable<Tv> 


这 个 和 lterable 类 似 ， 但 是 它 包含 key 的 类 型 。 它 添加 了 一 些 新 的 方法 ， 并 且 以 不 同 的 返回 类 型 对 lterable 中 的 一 些 方法 进行 了 覆盖 。 新 增加 的 方法 被 列举 在 前 面 : 


: array 返 回 一 个 由 Iterable 的 键 组 成 的 数组 。 


"toKeysArray () 
“toMap () : Map<Tk，Tv> 返 回 一 个 由 Iterable 转 化 成 的 Map。 
“keys () : Iterable<Tk>* 返 回 一 个 Iterable 上 面 的 所 有 key 组 成 的 Iterable。 
* mapWithKey<Tm> (function (Tk, Tv) : Tm$callback) 
* filterWithKey (function (Tk, Tv) : bool$callback) : KeyedIterable<Tk，Tv> 和 fter () 类 似 , 但 
* getIterator () : KeyedIterator<Tk，Tv> 是 一 个 拥有 更 特殊 返回 类 型 的 禾 盖 方法 。 

“ map<Tm> (function (T) : Tm$callback) 
* filter (function (T) 


: bool$callback) : Iterable<T> 是 一 个 拥有 更 特殊 返回 类 型 的 覆盖 方法 。 


“ zip<Tz> (Traversable<Tz>$traversable) 


5.4.2 ”常见 集合 接口 


: KeyedIterable<Tk，Tm> 和 map () 类 似 ， 但 是 会 把 键 和 值 一 样 传 回调 入 回调 函数 。 


是 会 把 key 和 value 一 样 传 入 回调 函数 。 


: KeyedIterable<TK，Tu> 是 一 个 拥有 更 特殊 返回 类 型 的 履 盖 方法 。 


: Iterable<Pair<T，Tz>> 是 一 个 拥有 更 特殊 返回 类 型 的 覆盖 方法 。 


这 里 有 三 大 核心 接口 ， 


于 声明 最 基本 的 集合 函数 功能 。 在 类 型 标注 方面 ， 你 基本 上 不 会 


到 它们 ， 


ConstCollection<T> 


一 个 关于 类 型 T 值 的 只 读 集合 。 它 和 以 下 几 方面 无 关 : 值 的 唯一 性 、 上 顺序、 基础 实现 或 其 他 。 


每 个 具体 的 集合 类 都 间接 地 实现 这 个 接口 。 这 个 接口 看 起 来 和 Map 不 搭配 ， 因 为 它 只 有 一 个 类 型 形 参 ， 而 Map 需 要 两 个 (一 个 
: 一 个 Map 拥 有 key 类 型 Tk 和 value 类 型 Tv， 实 现 了 ConstCollection<Pair<Tk，Tv> >。 


ConstCollection 接 | 


这 个 接口 声明 了 三 个 方法 : 


' count () : int， 返 回 该 集合 中 value 的 数量 。 
isEmpty () : bool， 返 回 该 集合 是 否 为 空 。 


“items () : Iterable<T> ， 使 用 foreach 时 ， 用 于 选 代 返 回 集合 中 的 每 一 个 值 。 


OutputCollection<T> 


这 个 接口 声明 了 两 个 方法 ， 


于 向 集合 中 添加 值 (每 个 可 变 集合 类 都 实现 这 个 接口 ) : 


“ add (TS$value) : this， 把 指定 的 值 添加 到 集合 中 ， 并 且 返 回 集合 本 身 。 


“addAll (? Traversable<T> 


values) 


Collection<T>extends ConstCollection<T>, OutputCollection<T> 


这 个 接口 没有 声明 任何 方法 ， 它 只 是 


5.4.3 ”特别 的 集合 接口 


: this， 对 于 给 定 的 Traversable 进 行 选 代 ， 然 后 添加 每 个 结果 值 到 集合 中 。 


最 后 ， 我 们 要 学 习 特 别 的 集合 功能 。 我 们 将 会 看 到 六 个 集合 接口 以 及 它们 所 声明 的 方法 [0。 它 们 是 
都 可 以 想象 为 关联 的 清单 ， 清 单 基于 实现 MutableVector 的 类 。 


因为 它们 并 没有 什么 特别 的 


途 。 我 们 在 这 里 将 学 习 它 们 的 核心 函数 : 


于 key 的 类 型 ， 另 外 一 个 


于 value 的 类 型 ) ， 但 是 Map 确 实 实现 了 


于 合并 ConstCollection 的 只 读 行为 和 OutputCollection 的 只 写 行为 。 


于 功能 描述 的 独立 实现 。 现 在 ， 每 个 都 只 有 一 个 具体 实现 ， 但 是 在 将 来 可 能 会 有 多 个 。 例 如 ， 每 个 


所 有 这 些 接口 都 直接 或 者 间接 继承 自 Keyedlterable， 其 中 声明 了 很 多 以 Keyedlterable 作 为 返回 类 型 的 方法 ， 例 如 map () 和 filter () 。 所 有 这 些 接口 都 以 特别 的 返回 类 型 对 这 些 方法 进行 了 覆盖 ， 例 
如 ConstVector<T> 声 明了 filter (function (T) : bool$callback) : ConstVector<T>。 这 些 履 盖 方 法 在 下 面 的 列表 中 简要 列 出 : 


ConstSet<T>extends ConstCollection<T>, KeyedIterable<mixed, T> 


它 代表 一 组 类 型 为 ?的 只 读 value[ 站 。 它 直接 只 声明 了 一 个 方法 : 


“ contains (T8value) : bool 返 回 给 定 的 值 是 否 在 该 组 中 存在 。 当 且 仅 当 该 组 中 有 一 个 值 ， 那 么 使 用 === 进 行 比 对 的 时 候 ， 将 和 $value 是 完全 相等 的 。 其 语义 上 和 === 恒 等 式 一 样 ， 结 果 将 返回 真 。 


MutableSet<T>extends ConstSet<T>, Collection<T> 


这 代表 类 型 为 T 的 一 组 可 变 值 。 它 继承 自 ConstSet， 并 且 直 接 声明 了 两 个 方法 : 


:clear () : this， 移 除 该 组 中 的 所 有 value， 然 后 返回 这 个 组 。 
.remove (TSvalue) : this， 将 指定 的 value 从 该 组 中 移 除 (如 果 该 组 中 没有 这 个 value， 那 么 不 会 做 任何 事情 ) ， 然 后 返回 该 组 。 如 同 contains () 、 语 义 和 === 恒 等 式 一 样 。 
ConstVector<T>extends ConstCollection<T>, KeyedIterable<int, T> 


它 代表 一 个 类 型 为 T 的 值 的 只 读 序列 ， 索 引 为 整 型 。 它 直接 声明 了 三 个 方法 : 


“at (int$index) : T 返 回 给 定 索引 映射 的 值 ， 如 果 索 引 越界 ， 就 会 抛 出 一 个 异常 。 
:containsKey (int$index) : bool 返 回 给 定 的 索引 是 否 在 范围 之 内 。 

“ get (int$index) : ? 返回 一 个 给 定 索 引 位 置 处 的 值 。 如 果 索 引 越界 ， 那 么 将 返回 null。 
MutableVector<T>extends ConstVector<T>, Collection<T> 


这 个 代表 一 个 类 型 为 T 的 可 变 值 序列 。 它 继承 自 ConstVector， 添 加 了 以 下 这 些 方 法 : 


“clear () : this， 移 除 该 vector 中 的 所 有 值 。 
:temoveKey (int$index) : this， 移 除 给 定 索引 对 应 的 值 。 根 据 vectot 的 语义 ， 高 位 索引 将 会 向 下 转移 一 位 ， 以 便 索 引 仍然 保持 连续 。 
“set (int$index，Tvalue) : this， 设 置 给 定 索引 位 的 值 为 给 定 的 值 ， 如 果 索 引 越界 ， 将 会 抛 出 一 个 异常 。 如 果 你 想 对 vector 进 行 扩展 ， 那 么 请 使 用 add () 。 
“setAll (KeyedTraversable$kt) : this， 对 于 给 定 的 KeyedTraversable 进 行 和 迭代 ， 然 后 对 里 面 的 每 个 key/value 对 调用 set () 方法 。 
ConstMap<Tk, Tv>extends ConstCollection<Pair<Tk, Tv>>, Keyedltera ble<Tk, Tv> 
这 代表 一 个 从 类 型 Tk 的 key 到 类 型 Tv 的 value 的 只 读 映 射 。 它 声明 了 与 ConstSet 以 及 ConstVector 类 似 的 方法 。 


“ at (Tk$key) : Tv， 返 回 给 定 key 对 应 的 值 ， 如 果 给 定 的 key 在 map 中 不 存在 的 话 ， 将 会 抛 出 一 个 异常 。 


“ contains (Tk$key) : bool， 返 回 给 定 的 key 在 map 中 是 否 存 在 。 

“containsKey (Tk$key) : bool， 和 contains () 一 样 ， 该 重复 的 方法 是 这 些 接口 继承 层面 上 的 一 个 特例 。 
:get (Tk$key) : ? Tv， 返 回 给 定 key 对 应 的 value， 如 果 key 在 map 中 不 存在 ， 则 返回 null。 
MutableMap<Tk, Tv>extends ConstMap<Tk, Tv> 


这 代表 一 个 从 key 到 value 的 可 变 映射 。 再 一 次 ， 它 所 声明 的 方法 是 MutableVector 和 MutableSet 方 法 的 一 个 合集 : 


“ clear () : this， 将 会 移 除 对 应 map 里 面 的 所 有 key 和 value。 
:remove (Tk$key) : this， 移 除 给 定 key 对 应 的 value。 

“ removeKey (Tk$key) : this， 这 个 和 remove () 方法 一 样 。 
“set (Tk$key，Tv$value) : this， 设 置 给 定 key 所 对 应 的 value。 


“setAll (KeyedTraversable<Tk，Tv>$kt) : this， 对 于 给 定 的 KeyedTraversable 进 行 选 代 ， 然 后 用 里 面 的 每 个 键 / 值 对 调用 set () 方法 。 


5.4.4 ”具体 的 集合 类 


最 后 ， 我 们 将 看 到 对 于 所 有 集合 类 一 个 完整 版 的 类 型 标注 API。 它 们 实现 了 前 面 小 节 中 六 个 接口 ， 并 且 添 加 了 一 些 有 用 的 方法 。 


我 们 这 里 只 列 出 类 本 身 定义 的 方法 ， 而 不 是 我 们 刚才 看 到 的 接口 中 声明 的 方法 : 
ImmVector<T>implements ConstVector<T> 
construct (? Traversable<T>$values) 用 给 定 的 Traversable 的 内 容 创 建 一 个 新 的 [mmVector。 
“linearSearch (TSvalue) : int 对 于 给 定 的 value， 在 ImmVector 中 执行 一 个 线性 搜索 ， 如 果 找 到 了 对 应 的 值 ， 那 么 将 返回 相关 的 索引 ， 如 果 没有 找到 ， 则 返回 一 1。 
"toString () : stting 仅 仅 返 回 "ImmVector"。 
Vector<T>implements MutableVector<T> 
* construct (? Traversable<T>$values) 用 给 定 的 Traversable 的 内 容 创建 一 个 新 的 Vectort。 


' linearSearch (TSvalue) : int， 对 于 给 定 的 value， 在 Vector 内 部 执行 一 次 线性 搜索 ， 如 果 找 到 了 对 应 的 值 ， 则 返回 对 应 的 索引 ， 否 则 返回 一 1。 


“ pop () : T 移 除 Vector 中 最 后 的 值 ， 并 且 返 回 它 。 

“reserve (int$size) : void 对 Vector 做 出 提示 ， 应 该 重新 分 配 内 存 空间 ， 以 便 能 够 保持 给 定数 量 的 value。 对 应 的 Vector 不 一 定 这 么 做 ， 这 仅仅 是 个 提示 。 

“resize (int$size，T$value) : void 把 Vector 的 大 小 数量 变 为 给 定 的 大 小 。 如 果 新 的 大 小 比 当前 小 ，Vector 尾 部 的 value 将 会 被 移 除 。 如 果 新 的 大 小 更 大 ， 那 么 新 的 value 将 会 被 设置 为 $value。 
.tevetse () : void 在 适当 位 置 逆转 对 应 的 Vector。 

shuffle () : void 对 Vector 中 的 值 随机 重新 排列 。 


' splice (int$offset，? int$len=NULL) : void 对 应 给 定 的 Vector， 从 $offset 开 始 ， 移 除 $len 个 value。 如 果 没 有 传递 $len 参 数 的 话 ， 它 将 把 从 $offset 开 始 到 这 个 Vector 末 的 所 有 值 都 移 除 。 这 个 方法 和 内 置 函 
数 array_splice () 非常 相似 。 


"toString () : string 仅 仅 返 回 "Vector"。 
ImmSet<T>implements ConstSet<T> 
* __construct (? Traversable<T>$values) 用 给 定 的 Traversable 的 内 容 创 建 一 个 新 的 ImmSet。 


* fromArrays (http://www.hzcourse.com/resource/readBook?path=/openresources/teach_ebook/uncompressed/16125/OEBPS/Text/..….) : ImmSet<T> 这 是 一 个 可 以 接收 大 量 实 参 的 静态 方法 ， 这 些 实 参 都 必 
须 是 array， 然 后 从 它们 的 内 容 中 创建 一 个 ImmSet。 


:fromItems (? Traversable<T>$items) : ImmSet<T> 这 是 从 给 定 的 Traversable 创 建 一 个 ImmSet 的 静态 方法 。 
“toString () : stting 仅 仅 返 回 "TImmSet"。 

Set<T>implements MutableSet< 工 > 

，__construct (? Traversable<T>$values) 用 给 定 的 Travetsable 的 内 容 创建 一 个 新 的 ImmSet。 


* fromArrays (http://www.hzcourse.com/resource/readBook?path=/openresources/teach_ebook/uncompressed/16125/OEBPS/Text/...) : Set<T> 这 是 一 个 可 以 接收 大 量 实 参 的 静态 方法 ， 这 些 实 参 都 必须 是 
atray， 然 后 从 它们 的 内 容 中 创建 一 个 ImmSet。 


* fromItems (? Traversable<T>$items) : Set<T> 可 以 从 给 定 的 Traversable 中 创建 一 个 ImmSet 的 静态 方法 。 
“ removeAll (? Traversable<T>$values) : Set<T> 从 set 中 移 除 给 定 的 Traversable 中 的 所 有 值 ， 并 且 返 回 set 本 身 。 
"toString () : string 仅 仅 返 回 "Set"。 
ImmMap<Tk, Tv>implements ConstMap<Tk, Tv> 
“construct (? KeyedTraversable<Tk，Tv>$values) 用 给 定 的 Traversable 的 内 容 创 建 一 个 新 的 ImmMap。 
“fromltems (? Traversable<Pair<Tk，Tv>>$items) : ImmMap 是 一 个 静态 方法 ， 可 以 从 给 定 的 Traversable 中 创建 一 个 ImmMap。 
“toString () : stting 仅 仅 返 回 "TImmMap"。 
Map<Tk, Tv>implements MutableMap<Tk, Tv> 
“construct (? KeyedTraversable<Tk，Tv>$values) 用 给 定 的 Traversable 的 内 容 创 建 一 个 新 的 [ImmMap。 
“fromltems (? Traversable<Pair<Tk，Tv>>$items) : ImmMap 是 一 个 静态 方法 ， 用 于 从 给 定 的 Traversable 中 创建 一 个 ImmMap。 
" toString () : string 仅 仅 返 回 "Map"。 


[1] 这 一 节 并 没有 讲述 所 有 的 故事 。 这 里 事实 上 在 图 中 有 其 他 六 个 接口 ， 分 别 是 SetAccess、ConstSetAccess 等 。 我 不 对 它们 中 的 每 个 细节 都 进行 阐述 的 主要 原因 就 是 : 它们 并 不 会 用 于 类 型 标注 中 ， 并 且 对 于 
集合 的 使 用 也 不 是 必 不 可 少 的 。 

四 你 也 许 想 知道 ， 为 什么 这 个 接口 继承 自 区 eyedIterable<mixed， 开 > ， 而 不 是 KeyedIterable<T，T>。 原 因 是 有 关 map0 类 型 的 一 个 微妙 问题 。KeyedIterable<T，T> 将 会 声明 一 个 map<Tm>0 函 数 ， 并 且 返 
回 KeyedIterable< 工 ，Tm>。 然 后 ，ConstSet<< 工 > 会 用 一 个 返回 ConstSet<Tm> 的 版 本 对 其 进行 覆盖 。 问 题 是 它们 不 兼容 : 在 KeyedIterable 二 T， Tm 中 ，key 和 value 的 类 型 可 能 是 不 同 的， 但 是 在 ConstSet 二 
Tm> 中 它们 必须 相同 。 使 key 的 类 型 为 mixed 看 起 来 有 些 不 雅 观 ， 这 在 将 来 的 版 本 中 可 能 会 通过 增加 新 的 类 型 检查 器 功能 来 改变 。 


5.5 与 数组 互 操作 


集合 就 像 其 他 的 Hack 特 性 一 样 ， 在 设计 之 初 就 考虑 到 互 操作 性 。 对 于 一 个 代码 库 来 说 ， 可 以 逐步 从 使 用 array 转 化 为 使 用 collection。 


5.5.1 ”转化 为 数组 


所 有 的 Hack 集 合 都 可 以 使 用 强制 转化 表达 式 转化 为 数组 ， 或 者 使 用 oArray () 方法 : 


$vector = Vector {'first', 'second'}; 
print r((array) $vector); // 输出 : Array( [0] => first, [1] => second ) 
print r ($vector->toArray ()); 一 样 


这 些 转 化 非常 简单 ， 且 易于 操作 : 
:Vector 和 ImmVectotr 转 化 为 array，key 将 会 是 value 的 整 型 索引 ， 并 且 顺 序 将 保持 不 变 。 


“Map 和 ImmMapb 转 化 为 array， 将 保持 相同 的 key/value 对 ， 顺 序 不 变 。 


' Set 和 ImmSet 转 化 为 array， 将 每 个 key 映 射 到 自己 ， 顺 序 不 变 。 
“ Pait 转 为 数组 ， 保 持 key 0 和 1 在 对 应 的 位 置 上 ， 指 向 相应 的 值 。 


关于 在 Map 和 Set 中 ， 类 似 整 型 的 字符 串 key (具体 参见 5.3.2 节 的 相关 内 容 ) 有 个 小 穿 门 。 如 果 Map 或 者 Set 包 含 这 种 方式 下 相互 冲突 的 key， 将 会 报告 一 个 E WARNING 级 别 的 错误 。 在 结果 数组 中 ， 
相互 冲突 的 key 将 会 减少 至 一 个 整 型 key， 并 且 它 将 会 映射 到 相互 冲突 的 key 中 后 面 的 那个 值 : 


<2php 
Smap = Map {10 => sin '10' => 'string'}; 
rg 器 7 (array) $map; 

: Map: :oarray() ) 正 应 用 在 同时 包含 int (10) 和 string('10') 的 Set 之 上 
Var ump (Sara9) ; // 输出 : array(1) { 0 string(6) "string" } 
$set = Set {10, "10"} 
Sarray = (array) $set; 
// 警告 : Set: :toArray() 正 应 用 在 同时 包含 int (10) 和 string('10') 的 Set 之 上 
var_dump ($array); // 输出 : array(1) { i string(2) "10" } 


5.5.2 ”使 用 内 置 及 用 户 函 数 


Hack 有 着 大 量 的 内 置 函 数 可 以 使 用 array 作 为 实 参 。 这 里 有 很 多 不 同 的 办 法 ， 可 以 使 它们 能 够 适 配 相应 的 集合 。 


内 置 排序 函数 


Hack 有 大 量 用 于 数组 排序 的 函数 。 所 有 这 些 函 数 都 可 以 在 使 用 集合 的 情况 下 正常 工作 。 但 是 每 一 个 都 只 和 特定 类 型 的 集合 一 起 工作 。 


“Vector 只 与 sort () 、atsort () 还 有 usort () 一 起 工作 。 其 他 的 排序 函数 都 和 key 有 关系 ， 显 然 都 不 适合 Vector 


“ Map 和 Set 可 以 和 asort () 、arsort () 、ksort () 、krsort () 、usort () 、uasort () 、uksort () 、nhatsott () 还 有 natcasesotrt () 一 起 工作 。 特 别 要 注意 ， 对 于 Set 来 说 ， 根 据 key 排 序 和 根据 value 排 
序 ， 效 果 是 一 样 的 。 


“ 不 可 变 集合 以 及 Pair 都 不 被 支持 ， 因 为 它们 是 不 可 变 的 。 如 果 需 要 的 话 ， 你 可 以 做 个 可 变 的 集合 副本 ， 然 后 对 其 进行 排序 。 


其 他 内 置 函 数 


剩余 的 内 置 函 数 采 用 了 多 种 办 法 用 于 处 理 array。 首 先 ， 它 们 分 为 几 类 : 


“ 四 个 可 以 修改 array 的 内 置 函数 ， 已 经 可 以 用 于 处 理 集合 : 
array_pop () 
array_push () 
array_ shift () 


array_unshift () 


其 他 的 还 不 能 用 于 集合 。 特 别 需 要 注意 的 是 ，array_push () 和 array_unshift () 只 支持 Vector 和 Set。 


* 用 于 读 取 或 者 修改 array 的 内 部 指针 的 内 置 函数 ， 例 如 current () 和 reset () ， 它 们 一 点 也 不 适 于 集合 ， 因 为 集合 中 并 没有 Hack 数 组 中 的 内 部 指针 的 等 价 概念 。 


用 于 调试 和 查看 数据 的 函数 ， 就 像 可 以 对 array 产生 的 输出 一 样 ， 它 们 可 以 对 集合 产生 对 应 的 输出 。 例 如 : 


Var _ dump (array (10, 20)); 
Var_dump (Vector {10, 20}); 


产生 输出 : 


array(2) { 
[0]=> 
int (10) 
[1]=> 
int (20) 


} 
object (HH\Vector)#1 (2) { 
[0]=> 
int (10) 
[1]=> 
int (20) 
} 


这 些 函 数 是 : 
—debug zval dump () 
—print r () 

—var dump () 

一 var_export () 


“serialize () 可 以 对 集合 collection 进 行 序列 化 ， 但 是 对 所 得 到 的 序列 化 字符 串 ， 只 有 HHVM 才 能 够 进行 反 序列 化 。 (集合 的 序列 化 和 其 他 的 对 象 是 不 同 的 。) 


关于 这 些 剩余 内 置 函数 最 常见 的 案例 就 是 ， 它 们 有 一 个 必须 为 array 的 形 参 ， 并 且 不 能 是 引用 。 这 些 例子 包括 count () 和 array _diff () 。 在 这 种 情况 下 ， 如 果 你 传递 了 一 个 collection 作 为 形 参 的 话 ， 
它 将 会 自动 转化 为 一 个 array[1]， 并 不 会 有 任何 的 警告 或 者 错误 。 


最 琼 手 的 事情 是 内 置 函 数 中 的 类 别 ， 它 们 的 行为 会 随 着 传 入 的 实 参 类 型 的 不 同 而 不 同 。apc_store () 就 是 这 样 一 个 例子 : 如 果 第 一 个 实 参 是 个 字符 串 ， 那 么 一 个 单独 的 值 会 被 存储 在 “可 选 PHP 缓 
存 ” (AlternativePHP Cache，APC) 中 ; 但 是 如 果 它 是 个 array， 此 array 中 的 所 有 的 key/value 映 射 都 会 在 APC 中 进行 存储 。 通 常 来 阅 ， 像 这 样 的 内 置 函 数 不 会 支持 集合 。 在 HHVM 3.6 中 唯一 的 特例 是 


implode () 。 


非 内 置 函 数 

对 于 拥有 array 类 型 提示 的 非 内 置 函 数 来 说 ，collection 将 会 隐 式 地 转化 为 array， 但 是 在 体 实际 操作 中 ， 这 里 会 有 个 E_NOTICE 级 别 的 错误 。 这 种 行为 的 理论 基础 是 ， 这 个 代码 很 可 能 在 你 控制 之 下 ， 所 
以 你 可 以 修改 它 来 使 之 拥有 一 个 集合 的 类 型 提示 ， 或 者 是 Indexish 或 者 是 Traversable， 或 者 其 他 合适 的 。 然 而 ， 它 也 可 能 不 在 你 的 控制 之 下 (比如 它 在 一 个 第 三 方 类 库 中 ) ， 所 以 把 这 个 错误 作为 一 个 致命 
错误 或 者 异常 都 太 严格 了 。 请 参见 下 面 的 代码 : 


function examine (array $items) { 
if (is array($items)) { 
echo "It's an array!"; 
} 


examine (Vector {1, 2, 3}); 


将 产生 如 下 输入 : 


Notice: Argument 1 to examine () must be of type array, HH\Vector given; 
argument 1 was implicitly cast to array 
It's an array! 


通过 对 比 ， 我 们 可 以 发 现 : 对 于 一 个 期 待 集合 作为 参数 的 用 户 函 数 ， 如 果 你 传递 一 个 数组 到 其 中 ， 不 会 发 生 隐 式 转化 ， 并 且 类 型 提示 将 会 失效 。 


四 出 于 效率 的 考虑 ， 一 些 内 置 函 数 已 经 能 够 直接 使 用 collection 了 ， 并 不 需要 把 它 转换 为 array， 但 是 最 终 的 效果 都 一 样 。 


第 6 章 异步 


典型 的 Web 应 用 将 会 需要 启动 耗 时 的 外 部 操作 ， 并 且 等 待 它 们 操作 结束 。 它 们 对 数据 库 进行 查询 ， 这 可 能 涉及 等 待 一 个 服务 器 在 网 络 上 读 取 旋转 式 硬盘 。 它 们 可 能 使 用 外 部 AP1， 这 可 能 涉及 在 网 络 上 
创建 HTTP 或 者 HTTPS 请 求 。 它 们 都 会 耗费 很 多 时 间 ， 如 果 应 用 本 身 不 支持 多 任务 ， 将 会 浪费 时 间 等 待 操 作 完成 ， 而 同时 不 能 做 任何 有 用 的 事情 。 

这 将 变 得 更 糟糕 : 如 果 一 个 非 多 任务 型 应 用 拥有 多 个 需要 同时 做 的 耗 时 操作 (〈 例 如， 两 个 独立 的 数据 库 查 询 ) ， 它 并 不 能 完成 。 它 必须 等 待 一 个 完成 ， 然 后 启动 下 一 个 ， 并 且 等 待 这 个 完成 ， 等 等 。 这 
种 低 效率 的 行为 会 迅速 增加 ， 并 且 是 巨大 的 浪费 。 对 于 高 流量 的 Web 应 用 来 说 ， 处 理 这 些 问题 的 一 些 多 任务 形式 是 非常 有 必要 的 。 一 些 PHP 扩 展 (例如 cURL 和 MySQLi) 已 经 支持 同时 执行 多 重 操作 ， 但 是 
它们 之 间 并 不 互 操作 。 


在 图 6-1 中 ， 两 个 查询 可 以 并 行 运行 ， 但 是 没有 办 法 进行 多 任务 处 理 ， 所 以 它们 每 次 只 能 运行 一 个 。 
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图 6-1: 没有 异步 的 情况 下 ， 执 行 两 个 数据 库 查 询 


像 PHP 一 样 ，Hack 并 不 支持 多 线程 ， 所 以 Hack 的 Web 应 用 需要 其 他 多 任务 形式 。 


这 就 是 异步 (async) 存在 的 目的 。 它 提供 了 实现 合作 式 多 任务 的 方法 ， 任 务 会 自愿 并 且 明 确 地 割让 CPU 的 使 用 权 给 另外 一 个 。 而 另外 一 面 是 抢占 式 多 任务 处 理 ， 在 任务 管理 器 的 管理 下 ， 任 务 可 能 会 
被 强制 中 断 。 


合作 式 多 任务 与 抢占 式 多 任务 相 比 有 着 很 多 的 优点 。 抢 占 式 多 任务 需要 对 安全 使 用 非常 重视 。 在 抢占 模式 下 ， 并 发 安全 是 普遍 需要 注意 的 问题 。 你 必须 对 临界 区 进行 保护 ， 同 时 对 共享 内 存 同 步 访问 数 
据 。 在 合作 式 多 任务 模式 下 并 没有 上 述 问题 。 因 为 每 个 任务 对 其 他 任务 产生 影响 的 时 候 ， 都 可 以 得 到 控制 。 对 于 临界 区 域 的 保护 问题 ， 它 并 不 需要 有 自己 特色 的 方式 : 它 需要 做 的 所 有 事情 就 是 避免 超 出 临 


界 区 域 。 


异步 提供 了 把 CPU 使 用 权 给 其 他 异步 任务 的 语法 ， 在 HHVM 内 部 存在 着 调度 机 制 ， 它 可 以 对 合作 式 多 任务 进行 管理 ， 用 于 决定 执行 哪个 异步 任务 以 及 开始 时 间 。 对 于 图 6-1 中 的 查询 ， 图 6-2 中 显示 了 如 
何 利用 合作 式 多 任务 ， 在 等 待 第 一 个 任务 完成 的 期 间 进 行 第 二 个 查询 ， 从 而 显著 降低 端 到 端的 查询 时 间 。 


"” 
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图 6-2: 异步 下 的 两 个 相同 查询 


在 本 章 中 ， 我 们 将 学 到 如 下 内 容 : 异步 函数 到 底 是 什么 ， 如 何 使 用 异步 函数 ， 围 绕 异 步 如 何 组 织 代码 结构 ， 如 何 使 用 HHVM 提 供 的 异步 扩展 。 


本 节 将 通过 一 些 异 步 函 数 的 小 示例 ， 展 示 异 步 函 数 的 大 体 概念 和 代码 组 织 框架 。 本 节 中 ， 我 们 将 略 过 大 部 分 的 细节 内 容 ， 留 待 本 章 的 余下 部 分 再 进行 详细 阐述 。 


异步 函数 和 普通 函数 之 间 有 两 个 句法 区 别 。 异 步 函 数 在 它们 的 头 部 function 关 键 词 之 前 有 一 个 async 关 键 词 。 同 时 在 它们 的 主体 内 部 可 以 使 用 await 关 键 词 。 对 于 异步 函数 ， 这 里 有 个 最 简单 的 例子 ， 供 
大 家 有 个 直观 的 认识 参考 : 


async function hello(): Awaitable<string> { 
return 'hello'; 


} 


无 论 是 静态 方法 还 是 非 静态 方法 ， 都 可 以 是 异步 的 : 


ClassC { 
public static async function hello(): Awaitable<string> { 
return 'hello'; 
} 
Public async function goodbye(): Awaitable<string> { 
return ‘goodbye'; 


闭 包 也 可 以 是 异步 的 ， 这 并 不 区 分 使 用 的 是 PHP 闭 包 语法 ， 还 是 Hack 的 拉 姆 达 表 达 式 语法 ( 见 3.4 节 的 相关 内 容 ) : 


Shello = async function () : Awaitable<string> { return 'hello'; }; 
$goodbye = async () =—> 'goodbye'; 


在 这 些 例子 中 ， 有 两 个 值得 注意 的 重要 事项 。 首 先 ， 异 步 函 数 并 不 需要 与 生 俱 来 就 是 异步 的 。 范 例 中 的 异步 函数 仅仅 返回 了 一 个 常量 结果 。 其 次 ， 异 步 函 数 有 个 特殊 的 返回 类 型 。 从 函数 的 主体 看 ， 它 
好 像 返回 了 字符 串 类 型 ， 但 是 在 运行 时 环境 ， 这 并 非 事情 的 全 部 。 对 一 个 异步 函数 的 调用 将 返回 一 个 对 象 ， 用 于 代表 一 个 可 能 准备 好 也 可 能 没有 准备 好 的 结果 值 。 正 如 返回 类 型 标注 解释 的 那样 ， 这 个 对 象 
实现 了 接口 Awaitable。 从 这 个 对 象 之 中 ， 你 可 以 得 到 异步 函数 给 在 它 的 返回 语句 中 所 返回 的 值 。 


区 并 步 画 数 的 返回 类 型 是 非常 独特 的 。 Awaitable 的 类 型 实 参 在 运行 环境 中 并 不 会 被 抹 去 。 在 异步 函数 中 ， 运 行 环境 对 传递 给 return 语 句 的 值 会 进行 类 型 实 参 检查 。 如 果 检 查 失 败 ， 将 会 抛 出 一 个 可 捕获 的 
致命 错误 。 这 和 对 其 他 类 型 标注 检查 失败 时 的 行为 保持 一 致 : 


<?hh // decl 
// Decl mode to silence typechecker error 


async function f(): Awaitable<string> { 
// Catchable fatal error at runtime 
return 100; 


} 


通过 使 用 异步 函数 基础 架构 的 awaiting， 就 可 以 在 Awaitable 对 象 外 部 获得 其 对 应 的 值 。 异 步 函 数 可 以 使 用 关键 词 await 来 等 待 一 个 异步 操作 的 结果 。 该 关键 词 之 后 的 表达 式 必 须 能 够 等 价 于 一 个 实现 了 
Awaitable 接 口 的 对 象 。 下 面 的 例子 从 另外 的 异步 函数 中 返回 符合 上 述 结论 的 一 个 对 象 : 


async function hello(): Awaitable<string> { 
return 'hello'; 


} 


async function hello world(): Awaitable<string> { 
S$hello = await hello(); 
return Shello . ' world'; 


} 


在 函数 hello_ world () 中 ， 第 一 个 将 要 被 执行 的 表达 式 是 对 hello () 的 函数 调用 ， 这 是 一 个 很 普通 的 调用 。 正 如 你 所 看 到 的 ， 它 的 返回 值 并 非 字 符 串 'hello'， 而 是 一 个 状态 未 定 的 结果 对 象 。 然 后 使 
await 关 键 词 来 告知 运行 时 ，“ 请 等 待 这 个 结果 准备 好 ， 然 后 返回 结果 值 ”。 


运行 时 句柄 将 会 检测 这 个 结果 值 是 否 准备 好 了 。 如 果 没有 准备 好 ， 运 行 时 会 暂停 hello_world () 的 执行 : 它 暂停 了 函数 的 执行 ， 保 存 了 它 的 执行 状态 。 然 后 ， 如 果 还 有 其 他 等 待 执行 的 异步 函数 ， 运 行 
时 会 从 中 选 出 一 个 继续 执行 。 


一 旦 结果 准备 好 ， 也 就 是 说 一 旦 函数 hello () 已 经 执行 了 一 条 返回 语句 ， 运 行 时 的 调度 函数 将 会 恢复 函数 hello_world () 的 执行 。 它 存储 了 hello_world () 的 执行 状态 ， 并 且 开 始 执行 
hello_ world () 的 主体 (在 await 表 达 式 后 面 的 那个 位 置 ) 。await 表 达 式 等 于 hello () 函数 向 它 的 return 语 句 中 传递 的 任何 值 ， 即 字符 串 'hello'。 这 个 值 随 后 被 赋予 局 部 变量 $hello， 到 此 为 止 ， 执 行 流程 
回归 正常 。 


但 这 仅仅 是 个 普通 的 例子 。 从 语法 级 别 向 上 进行 盘点 的 话 ， 为 了 充分 地 获得 异步 函数 所 带 来 的 好 处 ， 这 里 有 两 件 事 必须 要 做 : 使 用 异步 扩展 函数 ， 然 后 同时 等 待 多 个 异步 操作 。 


HHVM 对 于 四 个 种 类 的 操作 提供 异步 扩展 函数 : 对 MySQl 数 据 库 的 查询 ， 对 memcached 的 查询 ，cURL 请 求 ， 以 及 对 流 资源 的 读 写 。 下 面 是 关于 MySQL 和 cURL 的 异步 API 的 使 用 范例 : 


async function fetch from web () : Awaitable<string> { 
return await HH\Asio\cur] exec('https://www.example.com/'); 


} 


async function fetch from db (int $id): Awaitable<string> { 
$conn = await AsyncMysqlClient::connect( 
'127.0.0.1', 3306, ‘example', 'admin', ‘hunter2' 


) 7 
$result = await S$conn->queryf('SELECT name FROM user WHERE id = %d', $id); 
return $result->mapRows () [0] ['name']; 


请 注意 这 个 异步 版 本 的 代码 和 非 异步 版 本 的 代码 非常 相似 。 如 果 你 把 新 的 关键 字 移 除 掉 ， 然 后 对 类 名 及 函数 名 进行 修改 ， 以 使 用 非 异步 扩展 ， 它 将 等 价 于 非 异步 版 本 的 代码 。 这 里 并 不 需要 考虑 线程 或 
同步 的 使 用 。 关 键 词 async 和 await 是 唯一 实质 上 的 区 别 : 与 其 简单 调用 一 个 长 时 间 运 行 的 函数 ， 不 如 试 试 等 待 (await) 它 。 


异步 带 来 的 关键 性 好 处 还 在 于 它 可 以 同时 等 待 多 个 异步 操作 。 可 以 像 下 面 所 示 的 一 样 ， 同 时 运行 前 面 所 述 的 两 个 异步 函数 : 


async function fetch all(): Awaitable<string> { 
list (S$web, $db) = 
await HH\Asio\v (array (fetch from web(), fetch from db(1234))); 
return S$web . $db; 

} 


我 们 将 在 本 章 的 余下 篇 幅 里 面 对 这 里 所 发 生 的 事情 详细 阐述 ， 但 是 现在 你 对 异步 代码 有 较 高 层次 的 认识 即 可 。 


6.2 异步 细节 


在 我 们 正式 开始 之 前 ， 如 果 你 将 要 频繁 使 用 异步 ， 我 们 极力 推荐 你 安装 asio-utilities， 这 是 一 个 异步 的 助手 函数 库 。 我 们 将 在 接 下 来 的 学 习 中 对 这 个 库 的 内 容 进 行 探讨 。 当 然 ， 没 有 这 个 库 ， 你 也 可 以 
使 用 异步 ， 但 是 它 可 以 使 得 代码 更 加 简洁 。 


下 载 和 安装 这 个 类 库 的 推荐 途径 是 使 用 Composer (https://getcomposer.org/) ， 这 是 一 个 对 PHP 和 Hack 进 行 包 管理 的 工具 。 在 你 的 composerjson 文 件 中 添加 如 下 内 容 即 可 : 


"require": { 
"hhvm/asio-utilities": "~1.0" 
} 


6.2.1 ”等待 句柄 


等 待 句柄 (wait handle) 的 概念 是 异步 代码 工作 的 核心 内 容 。 等 待 句柄 是 一 个 对 象 ， 它 代表 了 一 个 可 能 的 异步 操作 ， 而 这 项 操作 可 能 完成 了 ， 也 可 能 没有 完成 。 如 果 它 完成 了 ， 你 可 以 从 等 待 句柄 中 获 
得 一 个 结果 。 如 果 没有 ， 你 可 以 等 待 这 个 句柄 。 


等 待 句柄 是 用 通用 的 接口 Awaitable 表 示 的 。 这 里 有 很 多 实现 了 这 个 接口 的 类 ， 但 这 些 都 是 实现 的 细节 ， 你 并 不 应 该 依赖 它们 。 


这 里 有 两 种 非常 重要 的 等 待 句柄 : 


“ 一 种 代表 了 蜡 步 函数 。 如 果 想 获得 其 中 一 个 ， 只 需 简 单 地 调用 一 个 异步 函数 : 


async function f(): Awaitable<int> { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 


async function main(): Awaitable<void> { 
Swait handle = 工 () 7 
// S$wait_handle 是 个 等 待 句柄 ， 它 的 值 类 型 为 Awaitable<int> 


$result = await S$wait handle; 
// $result 是 整 型 。 等 待 末 自 Awaitable"\ 展 开 “ 的 结果 
} 


: 另外 一 种 代表 了 多 个 其 他 的 等 待 句柄 。 为 了 得 到 其 中 一 个 句柄 ， 可 以 使 用 异步 助手 函数 [HHNAsio\v () 或 者 HH\Asio\m () 。 前 者 用 于 如 下 情形 : 当 你 已 经 有 一 个 等 待 句柄 的 索引 列表 时 ， 例 如 一 
个 Vector， 或 者 一 个 有 着 连续 整 型 键 的 数组 。 后 者 用 于 如 下 情形 : 当 你 拥有 一 个 等 待 句柄 的 对 照 关系 表 的 时 候 ， 例 如 一 个 Map 或 者 一 个 拥有 字符 串 键 的 数组 。 具 体 可 以 查看 下 面 的 例子 : 


async function triple (float $number): Awaitable<float> { 
return $number * 3.0; 
} 


async function triple v(): Awaitable<void> { 
Shandles = array( 
triple(3.0)， 
triple(4.0)， 


) 7 
$result = await HH\Asio\v (Shandles) 7 


var_dump ($result[0]); // 输 出 : float (9) 
var_dump ($result [1]); // 输 出 : float(12) 
} 


async function triple m() : Awaitable<void> { 
Shandles = array( 
"three' => triple(3.0), 
"four' => triple(4.0), 


); 
$result = await HH\Asio\m($handles); 


var_dump ($result['three']); // 输出 : float (9) 
var dump ($result['four']); // 输出 : float (12) 


HH\Asio\v () 把 一 个 Vector 或 者 Awaitable 类 型 的 数组 转换 为 一 个 Awaitable 类 型 的 Vector。 同 样 ，HHNAsio\m () 会 把 一 个 Map 或 者 Awaitable 类 型 的 数组 转换 为 一 个 Awaitable 类 型 的 Map。 


对 于 一 个 非 异步 函数 ， 如 果 想 获取 一 个 等 待 句柄 之 外 的 结果 ， 在 asio-utilities 中 有 个 叫做 HH\AsioNjoin () 的 函数 可 以 使 用 四。 它 只 有 一 个 Awaitable 类 型 的 实 参 。 这 个 函数 会 等 待 这 个 Awaitable 执 行 
完毕 ， 然 后 返回 它 的 结果 : 


async function f(): Awaitable<mixed> { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 


function main(): void { 
$result = HH\Asio\join(f()); 
} 


在 一 个 异步 函数 的 内 部 ， 你 不 应 该 使 用 HH\AsioNoin () 函数 。 如 果 你 这 样 做 了 ， 这 个 Awaitable 和 它 的 依赖 项 将 会 同步 完成 ， 你 当前 等 待 的 Awaitable 将 无 法 得 到 运行 的 机 会 。 如 果 在 一 个 异步 函数 内 
部 ， 你 将 会 得 到 一 个 等 待 句柄 ， 它 的 返回 结果 就 是 你 想 要 的 值 ， 请 耐心 等 待 。 


6.2.2 ”异步 和 可 调用 类 型 


在 1.4 节 中 ， 我 们 已 经 看 到 了 Hack 有 对 可 调用 值 类 型 进行 标注 的 相关 语法 。 在 这 个 例子 中 ， 你 必须 对 函数 f () 传递 另外 一 个 函数 作为 参数 ， 这 个 作为 参数 的 函数 以 一 个 整数 作为 参数 ， 并 且 返 回 一 个 字 
符 串 : 


function f((function (int) : string) $callback): void { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 


function main(): void { 
$good = function (int $x): string { return (string) $x; }; 


f($g009); // OK 


$bad = function (array $x): int { return count ($x); }; 


f£($bad) ; // 错 误 


现在 你 可 能 会 问 : 对 于 异步 函数 ， 你 如 何 实现 这 


函数 的 一 个 实现 细节 。 在 一 个 函数 上 使 


这 里 有 充分 的 理由 告诉 你 ， 你 不 能 这 样 做 。 函 数 的 异步 性 是 这 个 | 关键 词 async， 


: 它 允 许 这 个 函数 在 它 的 函数 体内 使 用 关键 词 await， 这 是 一 个 实现 细节 ， 而 不 是 关系 到 函数 外 部 的 任何 代码 的 东西 。 


“ 它 强制 函数 的 返回 类 型 为 Awaitable。 返 回 类 型 肯定 和 函数 外 部 代码 是 关系 。 但 是 这 个 关系 型 仅仅 局 限于 这 个 返回 值 ， 而 不 会 关系 到 函 


这 将 会 允许 (但 不 是 要 求 ) 


必须 返回 一 个 Awaitable<string>。 


为 了 返回 上 一 个 例子 , f() 可 以 指定 这 个 回调 


个 功能 呢 ? 在 本 例 中 ， 如 果 你 必须 传递 一 个 异步 函数 作为 回调 ，f () 该 如 何 指明 呢 ? 


会 做 如 下 两 件 事情 : 


元 数 的 异步 性 。 


一 个 异步 函数 作为 回调 传递 进来 : 


function f((function (int) : Awaitable<string>) $callback): void { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


i 


为 了 更 加 清晰 地 阐述 上 述 原 因 ， 考 虑 另外 一 个 函数 的 实现 细节 : 它 是 不 是 闭 包 。 在 这 个 例子 中 ，“ 人 允许 f() 指定 必须 传递 给 它 


为 是 一 样 思春 的 。 


一 个 异步 函数 ”和 “人 允许 f () 指明 必须 传递 给 


出 于 相同 的 原因 ， 对 于 抽象 方法 或 者 接口 中 的 方法 ， 并 不 能 声明 它们 为 异步 的 。 当 然 ， 可 以 声明 它们 为 非 异步 的 ， 还 可 以 把 Awaitable 作 为 它们 的 返回 类 型 : 


它 一 个 闭 包 ”， 这 两 和 


中 


Pe 


1 了 


interface I { 
public async function bad() : Awaitable<void>; // 错 误 
public function good(): Awaitable<void>; // OK 


} 


abstract class C { 
abstract public async function bad() : Awaitable<void>; // 错误 
abstract public function good(): Awaitable<void>; // OK 

} 


6.2.3 ”await 并 不 是 一 个 表达 式 


虽然 await 的 行为 从 很 多 角度 上 看 都 很 像 一 个 表达 式 ， 但 它 并 不 是 通常 意义 上 的 表达 式 。 这 里 有 它 可 以 出 现 的 三 个 句法 位 


:自己 作为 一 整 条 语句 : 


async function f(): Awaitable<void> { 
await other func(); 


i 


“ 在 通常 的 赋值 或 者 list 赋 值 语句 中 ， 出 现在 右边 : 


async function f(): Awaitable<void> { 

$result = await other func(); 

list($one, $two) = await yet another func(); 
} 


“作为 一 个 return 语 和 句 的 实 参 : 


async function f(): Awaitable<mixed> { 
return await other func(); 


} 


， 你 并 不 能 像 如 下 例子 一 样 使 用 它 : 


如 果 你 在 其 他 地 方 使 


await， 这 是 一 个 语法 错误 。 因 此 


Awaitable<void> { 


async function 工 () : 
// 语法 错误 


Var _dump (await other func ()) 7 


它 目前 存在 只 是 因为 一 些 实现 问题 B]。 


这 种 限制 可 能 在 将 来 解除 。 


6.24 “异步 生成 器 


生成 器 在 PHP 5.5 中 被 正式 引入 。 表 面 上 来 看 ， 它 们 看 起 来 和 异步 函数 非常 类 似 。 


这 两 个 特性 都 引入 了 一 种 特殊 的 函数 ， 它 们 具有 中 途 暂 停 执 行 的 能 力 。 以 这 样 的 方式 ， 它 们 可 以 再 次 回 到 离开 的 地 方 


恢复 执行 。 
然而 ， 这 两 种 特性 是 正 交 的 : 像 其 他 函数 一 样 ， 生 成 器 也 可 以 是 异步 的 。 这 里 有 一 个 例子 ， 它 实现 了 倒计时 的 时 钟 ， 每 一 秒 yield 一 次 (具体 参见 6.4.1 节 中 的 HH\Asio\usleep () 相关 内 容 ) : 
async function countdown (int Te AsyncIterator<int> { 
for ($1 = $start; $i >= 0; --$i) 
await HH\Asio\usleep (1000000); yy 休眠 1 秒 
yield $i; 
， } 
在 这 里 需要 特别 注意 的 一 点 就 是 返回 类 型 标注 : Asynclterator<int>。 这 意味 着 可 以 对 countdown () 函数 的 返回 值 进 行 迭 代 ， 并 且 你 得 到 的 迭代 值 为 整 型 。 


代 器 进行 迭代 ， 即 await as: 


于 对 异步 迭 


然而 ， 这 是 一 个 异步 迭代 ， 而 不 是 一 个 常规 迭代 。 这 里 有 一 些 新 的 语法 


async function use countdown(): Awaitable<void> { 
$async gen = countdown(); 
foreach ($async gen await as $value) { 
// 这 里 $value 的 类 型 为 int 
Var_dump ($value); 
} 
} 


await as 语 法 是 重复 调用 await$async_gen->next () 的 简写 ， 就 像 常见 的 foreach 语 法 是 在 一 个 常见 迭代 器 上 面 重 复 调 用 next () 的 缩写 一 样 。 


如 果 你 希望 从 一 个 异步 生成 器 中 得 到 一 个 键 ， 请 使 用 接口 AsyncKeyedlterator。 它 使 用 两 个 类 型 实 参 : 键 的 类 型 和 值 的 类 型 。 如 果 要 对 它们 中 的 某 一 个 进行 迭代 的 话 ， 你 也 可 以 使 用 await as: 


async function countdown (int $start): AsyncKeyedIterator<int, string> { 
for ($i = $start; $i >= 0; --$i) { 
await HH\Asio\usleep (1000000); 
yield $i => (string) $i; 
t 
} 


async function use countdown(): Awaitable<void> { 
foreach (countdown(10) await as Snum => $str) { 
// $num 是 个 整 型 
// $str 是 个 字符 串 型 
var dump ($num, $str); 
} 
E 


最 后 ， 如 果 你 希望 在 一 个 异步 生成 器 上 调用 send () 或 者 raise () 方法 ， 你 需要 使 用 接口 AsyncGenerator 作 为 替代 。 它 拥有 三 个 类 型 实 参 : 键 的 类 型 、 值 的 类 型 ， 以 及 你 希望 传递 给 send () 的 类 


async function namifier(): AsyncGenerator<int, string, int> { 
// 得 到 第 一 个 id 
$id = yield 0 => ''; 
// $id 的 类 型 为 int 


while ($id !== null) { 
Sname = await get name (Sid) 7 
$id = yield $id => $name; 
} 
} 


async function use namifier (array<int> $ids): Awaitable<void> { 
$namifier = namifier(); 
await $namifier->next (); 


// 注意 : 这 是 一 个 结构 性 非常 差 的 异步 代码 1 
// 仅 用 于 范例 演示 。 请 不 要 在 循环 中 使 用 await 


foreach ($ids as $id) { 
$result = await $namifier->send ($iqd); 
// $result 的 类 型 是 (int，string) 
} 
} 


有 一 些 非常 重要 的 事情 需要 指出 。 第 一 ， 虽 然 AsyncGenerator 的 第 三 个 类 型 实 参 是 int， 在 异步 生成 器 中 ， 一 个 yield 的 结果 是 type? int。 这 是 因为 把 null 传 递 给 send () 总 是 合法 的 。 (这 么 做 和 调用 
next () 效果 是 一 样 的 。) 


第 二 ，await$namifier->send ($id) 的 结果 是 类 型 ? (int，string) 。tuple 中 包含 yield 的 键 和 值 。 原 因 在 于 这 是 个 nullable 类 型 ， 就 是 说 借助 于 yield break， 生 成 器 能 够 总 是 隐 式 地 yield 到 null。 


加 


第 三 ， 请 记 住 在 一 个 异步 生成 器 上 ， 调 用 next () 、send () 以 及 raise () 的 时 候 ， 你 必须 要 等 待 它们 ， 而 不 仅仅 调用 它们 。 


回 


第 四 ， 异 步 迭代 器 (Asynclterator) 和 它 的 伙伴 们 会 从 它们 的 next () 方法 中 返回 真实 的 值 ， 而 不 是 返 
send () 和 raise () 方法 上 也 是 一 样 的 。 


void (就 像 非 异步 迭代 器 和 它 的 伙伴 们 所 做 的 那样 ) 。 同 样 的 道理 在 AsyncGenerator 的 


最 后 ， 这 个 代码 仅 用 于 示范 目的 ， 而 不 是 这 样 写 异步 代码 。 特 别 要 提醒 的 是 ， 干 万 不 要 在 一 个 循环 中 执行 等 待 ( 见 6.3.2 节 的 内 容 ) 。 遗 憾 的 是 ， 到 目前 为 止 ， 关 于 异步 生成 器 好 的 范例 代码 还 很 少 。 
为 这 里 并 没有 什么 扩展 使 用 到 它们 。 当 这 里 有 相关 代码 的 时 候 ， 异 步 生成 器 将 会 是 非常 强大 的 工具 。 例 如 ， 它 们 可 以 被 用 来 从 网 络 服务 上 实现 流 结果 。 


加 


6.2.5 “异步 函数 中 的 异常 


到 目前 为 止 ， 我 们 所 看 到 的 都 还 是 相当 简单 明了 的 : 当 你 调用 一 个 异步 函数 时 ， 它 返回 了 一 个 等 待 句柄 。 当 你 等 待 一 个 等 待 句柄 ， 你 得 到 了 它 的 结果 : 异步 函数 传递 给 它 的 return 语 句 的 值 。 但 是 如 果 
这 个 异步 函数 抛 出 了 异常 ， 将 会 发 生 什 么 事情 呢 ? 


答案 就 是 ， 当 等 待 一 个 等 待 句柄 时 ， 同 样 的 异常 对 象 将 会 被 再 次 抛 出 : 


async function thrower () : Awaitable<void> { 
throw new Exception () 7 


async function main(): Awaitable<void> { 
// 不 会 抛 出 
S$handle = thrower () 7 


// 抛 出 一 个 异常 ， 和 throwet () 函数 一 样 的 异常 对 象 


await $handle; 


如 果 你 使 用 HH\Asio\v() 或 者 HH\Asio\m () 同时 等 待 多 重 等 待 句柄 的 话 ， 并 且 其 中 一 个 组 件 等 待 句柄 抛 出 一 个 异常 ， 合 并 的 等 待 句柄 将 会 再 次 抛 出 那个 异常 。 如 果 多 个 组 件 等 待 句 柄 抛 出 异常 ， 合 
并 的 等 待 句柄 将 会 再 次 抛 出 其 中 的 一 个 。 然 而 ， 所 有 的 组 件 等 待 句柄 将 会 完成 ， 无 论 它们 是 正常 完成 还 是 抛 出 异常 : 


async function thrower (String $message): Awaitable<void> { 
throw new Exception ($message); 


} 


async function main(): Awaitable<void> { 
// 不 会 抛 出 
S$handles = [thrower('one'), thrower('two')]; 


// 抛 出 两 个 异常 对 象 中 的 一 个 
$results = await HH\Asio\v ($handles); 
} 


通常 ， 你 并 不 希望 发 生 异常 。 但 是 万 一 发 生 这 样 的 情况 ， 你 通常 希望 得 到 等 待 句柄 成 功 的 结果 值 ， 并 忽略 掉 其 余 的 ,或 者 换 一 种 方式 来 联络 失败 。 


asio-utilities 提 供 了 一 个 名 叫 HHN\Asio\wrap () 的 异步 函数 ， 它 采用 一 个 等 待 句柄 作为 实 参 。 它 将 会 等 待 你 传 入 的 等 待 句柄 ， 并 且 捕 获 它 抛 出 的 任何 异常 信息 。 如 果 没 有 任何 异常 发 生 ， 它 将 返回 一 个 
包含 传 入 的 等 待 句柄 的 结果 值 的 对 象 。 如 果 有 异常 发 生 ， 它 将 返回 对 应 的 异常 对 象 。 它 通常 以 HHN\Asio\ResultOrExceptionWrapper 的 形式 做 这 些 事情 。 


HH\Asio\ResultOrExceptionWrapper 是 asio-utilities 的 一 个 接口 ， 它 的 定义 类 似 下 面 : 


namespace HH\Asio { 

interface ResultOrExcept 
public function isSucc: 
public function isFail 
public function getRes: 


ionWrapper<T> { 
eeded () : bool; 
ed(): bool; 
lt 呈 


public function getException(): \Exception; 


ResultOrExceptionWrapp' 


“isSucceeded () 指明 了 内 


er 的 四 个 方法 是 : 


部 等 待 句柄 是 否 正 常 退出 。 (通过 return 退 出 ) 


“isFailed () 指明 了 内 部 等 待 句柄 是 否 非 正常 退出 。 (发 生 了 异常 ) 


:getResult () ， 如 果 内 部 等 待 句柄 正常 退出 ， 那 么 返回 句柄 的 结果 ， 否 则 将 会 重新 抛 出 异常 。 


“ getException () ， 如 果 内 部 等 待 句柄 抛 出 了 异常 ， 那 么 会 返回 对 应 的 异常 。 如 果 内 部 等 待 句柄 没有 抛 出 异常 ， 则 该 方法 将 会 抛 出 一 个 InvatiantException 异 常 。 


这 里 是 一 个 例子 : 


async function thrower () : 


throw new Exception () 7 


async function wrapped() : 


// 不 会 抛 出 
$handle = HH\Asio\wrap 


// 不 会 抛 出 


Awaitable<void> 1{ 


Awaitable<void> { 


(thrower () ) 7 


S$wrapper = await S$handle; 


if ($wrapper->isFailed 


() 


) { 
// 返回 thrower () 函数 抛 出 的 相同 异常 对 象 


$exc = $wrapper->getException (); 


} 


俯 本 节 中 的 合子 拥有 类 似 下 面 的 代码 : 


S$handle = thrower () 7 
await $handle; 


这 个 仅仅 用 于 明确 ， 对 异步 函数 的 调用 不 会 抛 出 一 个 异常 ， 并 会 正常 等 待 句柄 完成 。 一 般 来 说 ， 你 不 应 该 把 这 个 调用 和 这 样 的 await 分 离开 。6.5.1 节 的 相关 内 容 将 会 对 此 详细 解释 。 


6.2.6 ”映射 和 过 滤 助手 


当 并 行 地 创建 了 多 个 等 待 句 
函数 array_ map () 和 array filt 


er () (或 者 Hack 集 合 类 上 的 方法 ) 来 做 这 些 事情 ， 但 是 这 可 能 会 导致 你 的 代码 有 些 元 长 。 


柄 用 于 等 待 的 时 候 ， 你 经 常 将 会 有 一 些 值 的 集合 ， 它 们 中 的 每 一 个 都 需要 转化 为 等 待 句柄 ， 或 者 你 可 能 需要 把 它们 中 的 一 些 过 滤 出 去 。 你 可 以 使 用 平常 的 PHP 和 Hack 的 内 置 


asio-utilities 提 供 了 大 量 简明 的 命名 函数 用 于 处 理 异 步 映 射 和 过 滤 回 调 中 的 数组 及 集合 。 它 们 都 是 像 vm () 、vfk () 、mmw () 等 这 样 简明 的 名 字 ， 但 是 这 些 函 数 在 异步 代码 中 很 常用 ， 这 种 易 读 性 


的 损失 所 带 来 的 简明 性 ， 是 非常 


下 面 将 对 如 何 解码 这 些 名 字 


“ 第 一 个 字母 总 是 v 或 者 m。 


值得 的 。 


进行 详细 说 明 : 


这 表明 函数 的 返回 值 是 什么 : 一 个 Vector 或 者 一 个 Map。 


“ 接 下 来 ， 你 可 能 看 到 了 m、mk、f 或 者 化 。 这 些 意味 着 集合 内 的 这 些 值 ， 是 否 会 通过 一 个 映射 (m 和 mk) 或 者 过 滤 〈f 和 做) ， 传 递 一 个 回调 。 如 果 当 前 值 为 k， 这 意味 着 集合 内 的 键 也 将 会 传递 到 回调 


“ 最 后 ， 这 里 可 能 是 个 w。 如 果 是 这 样 的 话 ， 在 任何 的 映射 或 者 过 滤 被 执行 后 ， 集 合 内 的 值 通过 HHNAsioNvwtrap () 进行 传递 。 


第 一 个 参数 总 是 输入 的 数组 或 者 collection。 (这 个 助手 实际 上 接受 Traversable 或 者 KeyedTraversable， 视 情况 而 定 ， 所 以 你 也 可 以 传 入 迭代 器 。) 如 果 这 个 函数 需要 一 个 对 映射 或 者 过 滤 的 


callback， 这 就 是 第 二 个 实 参 。 


(没有 哪个 函数 会 需要 超过 1 个 callback。) 


映射 和 过 滤 的 回调 是 异步 函数 。 映 射 回调 必须 一 个 形 参 ， 或 者 两 个 形 参 。 当 为 一 个 形 参 的 时 候 ， 代 表 着 collection 的 value 类 型 。 当 为 两 个 形 参 的 时 候 ， 则 分 别 代表 着 collection 的 key 和 value 类 型 。 它 


们 可 能 返回 任何 类 型 。 过 滤 回 调 有 着 同样 的 形 参 规则 ， 并 且 它 们 必须 返回 布尔 值 。 


映射 是 非常 常见 的 : 你 将 会 有 一 个 异步 函数 ， 它 对 一 个 单独 的 值 ， 做 了 一 个 异步 操作 。 或 者 你 将 会 在 一 个 值 的 数组 或 者 集合 上 进行 映射 。 为 了 达到 这 个 目的 ， 你 可 能 使 


vm () 、vmk () 、 


mm () 、mmk () 或 者 在 这 些 函 数 名 称 后 面 带 w 的 其 他 函数 。 这 些 助手 的 最 基本 操作 是 : 通过 传递 它 到 异步 回调 ， 给 每 个 值 创 建 一 个 等 待 句柄 ， 然 后 并 行 等 待 所 有 这 些 等 待 句柄 ， 接 着 把 结果 值 放 到 一 个 


Vector 中 。 这 里 有 个 例子 向 我 们 


展示 了 : 当 使 用 一 个 Vector 以 及 一 个 Map 的 时 候 ， 将 会 发 生 什么 事情 : 


async function fourth root (num $f): Awaitable<float> { 


| 
throw new Exception () 7 


return sqrt (sqrt ($f£)); 


async function vector with mapping(): Awaitable<void> { 


$strs = Vector {16, 81} 


S$roots = await HH\Asio\vm($strs, fun('fourth root')); 


// S$roots 为 Vector {2, 


31} 


async function map with mapping wrapped() : Awaitable<void> { 


Snums = Map { 


"minus eighty-one' => -81, 


"sixteen' => 16, 


S$roots = await HH\Asio\mmw (Snums，fun('fourth root')); 


// S$roots['minus eighty-one'] 是 个 失败 的 ResultOrExceptionWrapper 


// S$Sroots['sixteen'] 是 


个 结果 为 2 成 功 的 ResultOrExceptionWrapper 


过 滤 就 不 是 那么 常见 了 。 你 将 会 使 用 一 个 结果 为 布尔 型 的 异步 函数 ， 且 并 行 地 把 它 应 用 到 一 个 集合 的 所 有 元 素 上 。 为 了 达到 这 个 目的 ， 你 将 会 使 用 vf () 、vfk () 、mf () 、mfk () ， 或 者 其 中 某 一 
个 的 函数 名 上 再 附加 一 个 w。 对 于 每 个 助手 ， 最 基本 的 操作 是 : 通过 把 它 传递 给 一 个 异步 回调 ， 为 每 个 值 创建 一 个 等 待 句 柄 。 然 后 对 原始 数组 或 者 集合 进行 过 滤 ， 结 果 值 会 是 个 布尔 型 。 例 如 : 


async function is user admin(int $id): Awaitable<bool> { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


async function admins from list (Traversable<int> $ids): Awaitable<Vector<int>> { 
return HH\Asio\vf ($ids, Fun('is user admin')); 
} 


值得 注意 的 是 ，HH\Asio\v () 和 HH\Asio\m () 并 不 是 asio-utilities 的 一 部 分 ， 它 们 内 置 在 HHVM 中 ， 所 以 在 Hack 代 码 中 总 是 有 效 的 。 


表 6-1 展 示 了 这 个 助手 函数 的 全 部 范围 ， 以 及 它们 的 功用 。 


表 6-1: asio-utilities 助 手 函 数 


返回 类 型 诈 传递 键 到 回调 ? 
v() Vector N/A 


vm() Vector Mapping No No 
vmk() Vector Mapping Yes No 
vf() Vector Filtering No No 
vfk() Vector Filtering Yes No 
vw() Vector Filtering Yes No 
vmw( ) Vector N/A N/A Yes 
vmkw() Vector Mapping Yes No 
vfw() Vector Mapping No Yes 
vfkw() Vector Filtering Yes Yes 


拉 姆 达 表 达 式 语法 ( 见 3.4 节 ) 和 这 些 异 步 助 手 函数 联合 使 用 起 来 是 非常 方便 的 。 拉 姆 达 表 达 式 可 以 减少 闭 包 语法 所 需要 的 模板 代码 。 下 面 改写 一 个 以 前 的 范例 。 


sync function root strings () : Awaitable<void> { 
$strs = array(!1 ‘817); 
S$roots = await ee $strs, async $str 一 > fourth root((float) $str)); 
// S$roots 为 Vector {2，3} 

} 


四 这 些 函 数 是 HHVM 的 内 置 函 数 。 它 们 并 不 是 asio-utilities 的 一 部 分 。 你 可 以 在 不 安装 这 个 类 库 的 前 提 下 ， 使 用 这 些 内 置 函 数 。 

[2] HHNAsioNjoin0 是 asio-utilities 的 一 部 分 ， 但 是 将 来 它 会 成 为 HHVM 的 内 置 函 数 。 通 常 来 说 ， 在 新 特性 合并 到 HHVM 自 身 之 前 ，asio-utilities 是 HHVM 团 队 测试 新 异步 API 的 地 方 

[3] 事实 上 ， 在 await 可 以 出 现 的 地 方 的 相关 约束 下 ， 这 里 没有 什么 办 法 能 够 使 一 个 异步 函数 能 在 执行 一 个 表达 式 的 中 途 暂停 。 如 果 await 能 够 在 任意 地 方 出 现 ， 我 们 将 会 面临 的 问题 就 是 如 何 有 效 地 存储 表达 式 
的 中 间 计 算 状 态 。 这 可 并 不 是 听 起 来 那么 简单 的 事情 


6.3 ”构建 异步 代码 


正如 我 们 所 看 到 的 ， 在 一 个 单一 的 函数 内 ， 异 步 代 码 看 起 来 和 原生 序列 代码 非常 相似 。 这 个 原因 非常 简单 。 在 这 种 级 别 上 ， 你 并 不 需要 适应 一 种 不 熟悉 的 新 思考 方法 。 


但 是 ， 为 了 获得 更 多 异步 所 带 来 的 好 处 ， 你 可 以 对 代码 做 更 高 级 别 的 代码 组 织 。 比 如 ， 什 么 样 的 函数 里 面 放置 什么 样 的 数据 ， 以 及 如 何 把 这 些 函 数组 织 起 来 。 这 就 需要 对 相互 之 间 的 数据 依赖 关系 有 着 
更 高 的 思考 。 也 就 是 这 样 的 想法 : 为 了 创建 一 段 数据 ， 你 需要 一 些 其 他 的 数据 。 


在 本 节 中 ， 我 们 将 会 看 到 如 何 根据 数据 依赖 关系 划分 程序 代码 逻辑 ， 以 及 如 何 将 传统 数据 依赖 转化 为 异步 代码 。 我 们 还 将 对 一 些 常见 的 反 模 式 进行 了 解 ， 知 道 为 什么 应 该 避免 它们 。 


6.3.1 数据 依赖 


在 一 个 博客 程序 中 ， 生 成 一 个 有 关 某 作者 的 文章 列表 页 面 ， 可 能 需要 如 下 的 一 系列 查询 : 


1. 取 得 这 个 作者 文章 的 ID， 可 能 是 所 有 的 文章 ， 或 者 只 是 前 20 篇 或 其 他 数量 。 


2. 取 得 每 篇 文章 ID 的 数据 (标题 、 摘 要 等 ) 。 


3. 取 得 每 篇 文章 ID 的 评论 数量 。 


理解 一 组 数据 依赖 关系 最 直观 的 方式 就 是 使 用 一 副 图 。 图 6-3 显 示 了 这 个 方案 的 依赖 性 。 箭 头 代表 数据 流 的 方向 ， 例 如 ， 顺 着 箭头 方向 ， 我 们 可 以 看 到 “每 篇 文章 ID” 流 向 “获取 文章 数据 ”。 


图 6-3: “ 某 作者 的 全 部 文章 ”页 面 的 依赖 关系 


学 习 如 何 良 好 地 组 织 异 步 代 码 牵扯 到 对 依赖 关系 图 的 识别 模式 学 习 ， 以 及 把 他 们 翻译 为 异步 函数 代码 。 这 个 方案 中 包含 一 些 很 常见 模式 的 例子 : 


1. 放 置 每 条 “链子 ” (一 个 没有 分 支 的 依赖 序列 ) 到 它 自己 的 异步 函数 中 。 


2. 放 置 每 一 组 并 行 的 链条 到 它们 自己 的 异步 函数 中 。 
3. 现 在 ， 每 组 并 行 的 链条 已 经 缩减 到 一 个 单一 函数 。 那 么 返回 到 第 一 步 中 ， 这 里 可 能 还 有 一 条 新 的 链条 等 待 缩减 。 
请 注意 ，“ 它 自己 的 异步 函数 ”并 不 一 定 意味 着 一 个 命名 的 函数 。 出 于 代码 的 整洁 性 和 可 读 性 考虑 ， 闭 包 经 常 是 最 好 的 选择 (请 记 住 ， 闭 包 也 可 以 是 异步 的 ) 。 


在 这 个 方案 的 页 面 请 求 过 程 中 ， 你 的 目标 应 该 是 去 适应 必须 发 生 在 其 中 的 每 个 异步 操作 。 在 最 顶层 的 代码 中 ， 你 应 当 只 调用 HHN\AsioNoin () 函数 一 次 。 并 且 相 应 的 结果 应 该 就 是 这 个 页 面 请 求 结果 的 
全 部 。 


关于 “ 某 个 作者 的 文章 ”页 面 ， 我 们 将 会 使 用 这 个 方案 来 把 这 些 异 步 操作 划分 到 这 些 异步 函数 之 中 : 
“ 一 个 函数 对 应 一 个 基础 的 获取 操作 : 获取 这 个 作者 的 所 有 文章 ID， 获 取 某 篇 文章 的 数据 ， 以 及 获取 评论 数量 。 
“ 一 个 函数 把 文章 数据 以 及 评论 数 成 组 打包 。 这 将 会 是 在 最 顶层 函数 中 的 一 个 闭 包 。 
“ 一 个 顶层 函数 负责 协调 所 有 的 数据 获取 。 
什么 样 的 函数 应 该 是 异步 的 ? 


不 要 害怕 使 用 一 个 异步 防 数 ， 即 使 这 个 函数 通常 来 说 并 不 需要 等 待 什么 (或 者 从 不 等 待 什么 ) 。 如 果 它 能 够 更 好 地 帮助 函数 和 代码 进行 匹配 融合 ， 或 者 如 果 它 在 将 来 可 能 需要 是 异步 的 ， 那 么 请 把 它 改 
写成 异步 函 数 ， 这 里 并 不 会 有 什么 性 能 上 的 损耗 。 


所 以 ， 关 于 “ 某 作者 的 全 部 文章 ”页 面 的 相关 代码 ， 很 有 可 能 是 这 样 的 : 


async function fetch all post ids for _ author (int $author id) 
: Awaitable<array<int>> { 
// 查询 数据 库 等 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 


async function fetch post datalint $post id): Awaitable<PostData> { 

// 查询 数据 库 等 

// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 


async function fetch comment count (int $post id): Awaitable<int> { 

// 查询 数据 库 等 

// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 


async function fetch page datal(int $author id) 
: Awaitable<Vector< (PostData, int)>> { 
$all post ids = await fetch all post ids for author ($author id); 


// 一 个 异步 闭 包 ， 将 会 把 一 个 文章 ID 转化 为 文章 数据 和 评论 数 元 组 
$post_fetcher = async function (int $post id) : Awaitable< (PostData, int)> { 


Tist($pPost data, $comment count) = 
await HH\Asio\v (array( 
fetch post data($post id), 
fetch comment count ($post id)， 
)); 
return tuple($post data, $comment count); 
}; 


// 把 文章 的 ID 数组 转化 为 结果 数组 

// 使 用 来 自 asio-utilities 的 vm() 函数 

return await HH\Asio\wm($all post ids, $post fetcher); 
} 


async function generate pagel(lint $author id) : Awaitable<string> { 
Stuples = await fetch page data ($author id); 


foreach ($tuples as $tuple) { 
list($post data, $comment count) = $tuple; 


// 把 数据 泻 染 到 HTML 中 


// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


智能 数据 获取 


请 注意 ， 上 述 例子 仅仅 使 用 一 个 通俗 易 懂 的 应 用 ， 向 读者 展示 了 如 何 组 织 异 步 代 码 的 结构 。 考 虑 到 应 用 的 后 台 存 储 机 制 以 及 你 如 何 对 它们 进行 设置 ， 可 能 需要 使 用 /OIN 或 者 其 他 语句 对 数据 库 进行 查 


至 少 ， 这 个 例子 应 该 建立 一 次 对 数据 库 的 连接 ， 并 且 把 这 个 连接 对 象 传递 到 上 下 文 环境 中 由， 而 不 是 为 每 个 像 fetch_post_data () 的 获取 函数 自身 建立 一 个 连接 。 


当 你 使 用 异步 和 你 的 后 台 存 储 进 行 通信 的 时 候 ， 很 有 可 能 仍然 是 非常 低 效 的 。 异 步 并 不 代表 你 不 再 需要 考虑 下 面 的 事情 ， 例 如 智能 读 取 缓 存 、 批 处 理 获取 、 建 立 高 效 的 SQL 查询 。 


6.3.2 反 模 式 


在 开始 的 时 候 ， 这 里 有 一 些 组 织 异步 代码 的 方式 ， 看 起 来 令 人 难以 抗拒 。 但 事实 上 ， 这 对 于 异步 代码 可 以 更 有 效 利用 时 间 的 能 力 是 个 损害 。 


反 模式 就 是 创造 了 错误 的 依赖 关系 。 尽 管 一 个 等 待 句 柄 并 不 需要 等 待 男 外 一 个 ， 但 是 它们 导致 了 这 种 等 待 (通常 来 说 是 间接 的 ) 。 好 的 异步 代码 会 忠实 地 把 纯正 、 理 想 的 依赖 关系 图 翻译 成 代码 。 


在 循环 中 等 待 


设想 你 有 一 个 用 户 1D 的 数值 数组 ， 还 有 一 个 异步 函数 ， 根 据 给 定 的 用 户 ID 装 载 对 应 的 用 户 数据 (比如 说 从 数据 库 进 行 装载 ) 。 你 希望 把 用 户 1D 的 数组 转化 为 用 户 对 象 的 数组 。 那 么 下 面 这 样 做 很 有 诱惑 


async function load user(int $id): Awaitable<User> { 
// 调 用 memcache 或 者 数据 库 等 
} 


async function load users (array<int> $ids): Awaitable<Vector<User>> { 
$result = Vector {}; 
foreach ($ids as $id) { 
$result[] = await load user ($id); 


return $result; 


网 


这 段 代 码 彻 诡 违 背 了 异步 函数 的 初 束 。 所 有 的 用 户 将 会 被 一 个 接 一 个 地 串 行 加 载 ， 而 根本 不 是 并 行 的 。 这 段 代 码 创建 了 一 条 单一 长 链 的 依赖 关系 


但 这 是 个 错误 的 依赖 : 在 开始 加 载 第 二 个 用 户 之 前 ， 你 并 不 需要 等 待 第 一 个 用 户 加 载 完 成 。 在 真实 的 依赖 图 中 ， 没 有 哪个 用 户 的 加 载 依赖 于 其 他 的 用 户 。 它 看 起 来 应 该 是 这 样 的 : 


为 了 把 真实 的 依赖 关系 图 转化 为 代码 ， 请 这 样 做 (vm () 函数 见 6.2.6 节 相关 内 容 ) 


async function load users (array<int> $ids): Awaitable<Vector<User>> { 
return await HH\Asio\vwm($ids, fun('load user')); 
} 


通常 情况 下 ， 如 果 你 试图 在 一 个 循环 中 等 待 ， 可 能 是 由 于 有 一 些 集合 之 类 的 东西 需要 等 待 。 在 这 种 情况 下 ， 你 应 该 使 用 相关 的 集合 等 待 助 手 冰 数 ( 辅 以 array_ map () 和 array filter () 等 ) ， 而 不 是 
对 集合 进行 迭代 ， 然 后 在 一 个 循环 中 等 待 。 


自 请 容许 我 重复 说 明 一 下 : 在 一 个 循环 中 进行 等 待 从 来 都 是 不 对 的 。 到 目前 为 止 ， 这 是 初学 者 最 容易 掉 进 去 的 陷阱 ， 这 会 彻底 抵消 异步 带 来 的 好 处 。 请 不 要 在 一 个 循环 中 使 用 等 待 。 


多 重 ID 模 式 
让 我 们 回顾 一 下 “ 某 作者 的 所 有 文章 ”的 例子 。 设 想 一 下 ， 在 每 篇 文章 里 面 ， 我 们 需要 的 不 是 两 个 平行 查询 ， 而 是 两 个 有 依赖 的 查询 。 这 就 是 说 ， 我 们 先 执行 一 个 查询 ， 然 后 使 用 它 的 结果 组 织 另外 一 
个 查询 。 


例如 ， 如 果 我 们 希望 在 每 篇 文章 上 显示 第 一 条 评论 的 内 容 。 那 么 开始 的 时 候 ， 我 们 需要 获取 每 篇 文章 第 一 条 评论 的 ID， 然 后 我 们 需要 获取 这 些 评论 的 内 容 四 。 


我 们 可 能 使 用 下 面 的 代码 来 实现 这 个 逻辑 : 


async function fetch first Comet ._ ids (array<int> $post ids) 
: Awaitable<array<int>> 
// 用 所 有 的 文章 的 ID， 发 送 单一 区 数据 库 查询 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


} 


async function fetch comment text (array<int> $comment ids) 
: Awaitable<array<string>> { 
// 使 用 所 有 的 评论 TD， 发 送 单一 的 数据 库 查询 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


} 


async function fetch all first comments (int $author id) 
: Awaitable<array<string>> { 
$all post ids = await fetch all post ids for author ($author id); 
$all comment ids = await fetch first comment ids($all post ids); 
return await fetch comment text($all comment ids); 
} 


只 对 数据 库 进 行 两 次 查询 是 一 个 显而易见 的 优势 保证 ， Ce 
赖 关系 图 。 特 别 注 意 获 取 任 何 评论 的 文本 间接 依赖 于 每 个 评论 1D 的 获取 ， 这 是 没有 意义 的 。 


图 6-4: “第 一 条 评论 ”不 好 的 代码 依赖 关系 图 
此 反 模 式 的 现象 就 是 ， 该 异步 函数 取 多 重 ID， 或 者 查找 任意 表单 的 键 作 为 参数 。 它 们 创建 了 这 些 水 平 的 虚假 依赖 关系 ， 进 而 演变 成 了 瓶颈 。 


我 们 应 该 创建 真实 的 依赖 关系 图 并 没有 这 些 水 平 的 依赖 关系 : 获取 每 个 评论 的 文本 ， 仅 依赖 于 获取 这 个 评论 的 ID， 并 没有 其 他 的 。 图 6-5 显 示 了 依赖 关系 图 应 该 是 什么 样 的 。 


图 6-5: “第 一 条 评论 ”页 面 的 正确 依赖 关系 图 


我 们 可 以 根据 先前 的 指导 方针 ， 以 及 依赖 关系 的 链条 打包 分 组 到 他 们 自己 的 函数 ， 把 这 个 关系 图 翻译 成 代码 。 在 这 种 情况 下 ， 我 们 为 每 篇 文章 把 链条 打包 成 组 到 一 个 闭 包 : 


async function fetch first comment (int $comment id): Awaitable<int> { 
// 使 用 单独 的 文章 ID， 发 送 数据 库 查 询 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach_ebook/uncompressed/16125/OEBPSVText/... 


async function fetch comment text (int $comment id) : Awaitable<string> { 

// 使 用 单独 的 评论 ID， 发 送 数据 库 查 询 

// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 


async function fetch all first comments (int $author id) 
: Awaitable<Vector<string>> { 
$all post ids = await fetch all post ids for author ($author id); 


$comment fetcher = async function(int $post id): Awaitable<string> { 
$first comment id = await fetch first comment ($post id); 

return await fetch comment text ($first comment id); 

1 


return await HH\Asio\wm($all post ids, $comment fetcher); 
} 


这 段 代码 有 着 可 能 导致 更 多 次 数据 库 查 询 的 潜在 缺点 ， 因 为 它 缺乏 一 次 性 发 送 多 个 1D 到 一 个 查询 中 的 能 力 。 这 个 问题 可 以 得 到 解决 ， 完 成 和 异步 的 无 颖 对 接 。 具 体 细节 参见 6.4.2 节 的 相关 内 容 。 


从 这 些 反 模式 得 到 的 教训 就 是 应 该 总 是 优先 考虑 数据 结构 。 让 数据 来 通知 你 如 何 组 织 代码 。 干 万 不 要 先 写 代码 ， 然 后 再 弄 清 楚 这 段 代 码 创建 了 什么 样 的 依赖 关系 。 


四 关于 异步 MYSQL API， 详 情 请 见 6.6.1 节 的 相关 内 容 。 
D] 这 可 能 看 起 来 很 奇怪 ， 因 为 一 个 典型 的 、 标 准 化 的 数据 库 方案 并 不 需要 获取 评论 ID 的 中 间 步 又 。 然 而 ， 在 非 规范 化 的 方案 中 这 也 许 是 不 可 能 的 。 它 有 其 存在 的 优势 ， 并 且 经 常 在 实践 中 被 使 用 。 


6.4 其 他 类 型 的 等 待 


你 所 处 理 的 大 多 数 等 待 句柄 将 会 代表 异步 函数 和 多 个 其 他 等 待 句柄 。 其 中 有 两 类 其 他 类 型 的 等 待 非常 有 用 。 


6.4.1 休眠 


你 可 以 使 用 一 个 等 待 句柄 来 等 待 渡 过 一 定 长 度 的 时 间 。 在 此 期 间 ，CPU 并 没有 什么 工作 要 做 。 这 和 调用 内 置 函 数 usleep () 殊途同归 ， 但 是 使 用 等 待 句柄 在 休眠 期 间 会 允许 其 他 等 待 句柄 的 运行 。 


asio-utilities 提 供 了 一 个 休眠 的 函数 HH\Asio\usleep () 。 它 取 一 个 实 参 ， 即 要 休眠 的 时 间 长 度 ， 单 位 是 微 秒 [1]: 


async function sleepForFiveSeconds(): Awaitable<void> { 
echo "start\n"; 
await HH\Asio\usleep (5000000); // 5 百 万 微 秒 =5 秒 
echo "finish, at least five seconds later\n"; 


} 


值得 注意 的 是 ， 第 二 个 echo 发 生 在 至 少 5 秒 之 后 ， 并 不 是 准确 的 5 秒 之 后 。 当 这 个 等 待 句柄 休眠 的 时 候 ， 另 外 一 个 可 能 正在 运行 ， 占 用 CPU 超过 5 秒 。 这 种 情况 下 ， 异 步调 度 管理 并 不 会 打 断 它 。 


6.4.2 ”重新 调度 


对 一 个 等 待 句柄 进行 重新 调度 意味 着 把 它 发 送 到 异步 调度 队列 的 后 面 ， 然 后 自愿 等 待 ， 直 到 其 他 挂 起 的 等 待 句柄 开始 运行 。 这 里 有 两 个 你 可 能 这 样 做 的 原因 : 和 其 他 异步 操作 一 起 循环 轮 询 ， 以 及 做 批 
处 理 。 


轮 询 


理想 情况 下 ， 你 的 代码 将 通过 异步 扩展 来 做 所 有 的 异步 工作 。 然 而 ， 你 可 能 需要 使 用 一 些 没有 相应 扩展 的 服务 。 你 可 能 使 用 调度 来 使 得 这 些 服务 能 够 和 你 的 异步 代码 一 起 协调 工作 。 


关键 在 于 ， 你 必须 能 够 对 该 服务 进行 非 阻塞 调用 。 如 果 能 这 样 做 的 话 ， 你 可 以 在 轮 询 中 使 用 重新 调度 ， 以 达到 “不 成 功 则 允许 其 他 等 待 句柄 运行 ”的 目的 。 


asio-utilities 提 供 了 一 个 重新 调度 的 函数 : HHNAsioNlater () ， 它 没有 任何 实 参 。 所 有 你 需要 做 的 就 是 调用 和 等 待 : 


async function poll for _ result (PollingService S$svc) : Awaitable<mixed> { 
while (!$svc->isReady()) { 
await HH\Asio\later () 7 
+ 
return $svc->getResult (); 


} 


如 果 这 里 没有 其 他 等 待 句柄 运行 的 话 ， 这 就 相当 于 一 个 轮 询 的 忙 循环 。 根 据 轮 询 操作 的 代价 是 否 昂贵 ， 以 及 对 应 服务 延迟 预期 的 基础 情况 ， 你 可 能 希望 使 用 HH\Asio\usleep () 函数 作为 蔡 代 进行 休眠 
操作 。 


批 处 理 


新 调度 也 可 以 帮助 你 。 关 键 在 于 你 编写 一 个 异步 函数 ， 它 在 重新 调度 后 做 一 个 批 处 理 操作 ， 这 使 得 其 他 等 待 句柄 获得 了 一 个 机 


如 果 你 正在 做 一 些 可 能 受益 于 批 处 理 的 高 延迟 操作 (如 数据 库 查 询 ) ， 
会 ， 可 以 把 他 们 的 项 目 添加 到 批 处 理 操作 中 。 


由 | 


在 这 个 例子 中 可 以 这 样 设想 一 下 ， 我 们 的 底层 异步 操作 是 一 个 键 / 值 查找 操作 ， 并 且 需 要 在 网 络 到 存储 服务 器 上 进行 一 个 回合 。 每 次 往返 都 是 高 延迟 的 ， 但 是 你 可 以 在 一 个 单一 请 求 中 发 送 多 个 键 ， 而 这 
并 不 会 增加 整体 时 间 。 (memcached 的 行为 和 这 个 有 些 像 ， 但 是 我 们 不 会 使 用 它 的 特殊 APl。) 


使 用 这 个 操作 的 代码 可 能 看 起 来 是 这 样 的 : 


async function one (string $key): Awaitable<string> { 
$subkey = await Batcher::]lookup ($key); 
return await Batcher::lookup ($subkey); 

} 


async function twol(string $key): Awaitable<string> { 
return await Batcher::lookup ($key); 
} 


async function main(): Awaitable<void> { 
$results = await HH\Asio\v (array (one('hello'), twol('world'))); 
echo $results[0]; 
echo $results[1]; 

} 


如 果 Batcher: : lookup () 直接 迅速 地 完成 了 查找 操作 ，one () 和 two () 这 两 个 函数 的 执行 将 导致 到 存储 服务 器 的 三 个 回合 查询 合并 成 一 个 查询 。 然 而 ， 这 里 有 一 个 优化 的 机 会 : 如 果 你 能 够 在 单 
一 的 回合 中 ， 执 行 one () 中 的 第 一 个 查询 以 及 two () 中 的 查询 ， 那 么 我 们 将 会 总 计 两 个 回合 就 完成 全 部 的 查询 。 


这 里 有 个 关于 Batcher 类 的 代码 实现 ， 供 我 们 参考 : 


class Batcher { 
private static array<string> $pendingKeys = array(); 
private static ?Awaitable<array<string, string>> $waitHandle = null; 


public static async function lookup (String $key): Awaitable<string> { 
// 把 这 个 键 添加 到 批 处 理 中 
self::$pendingKeys[] = $key; 


// 如 果 这 里 没有 要 开始 的 等 待 句柄 ， 创 建 一 个 新 的 

if (self::$waitHandle =—= null) { 
self::$waitHandle = self::g0o(); 

} 


// 等 待 批 处 理 完成 ， 然 后 从 中 拿 到 我 们 的 结果 
$results = await self::S$waitHandle; 
return $results[$key]; 


} 


Private static async function go(): Awaitable<array<string, string>> { 
// 让 其 他 的 等 竺 句柄 进入 这 个 批 处 理 之 中 
await HH\Asio\later (); 
// 现 在 这 个 批 处 理 启动 了 ， 清 除 共享 状态 
$keys = self::$pendingKeys; 


self::$pendingKeys = array(); 
self::$waitHandle = null; 


// 做 多 重 键 的 回合 操作 


return await multi key lookup ($keys); 


私有 静态 属性 $waitHandle 代 表 了 一 个 将 要 启动 的 批 处 理 
成 ， 然 后 检索 它 感 兴趣 的 结果 。 


回 


合 。 公 共 方 法 lookup () 负责 检查 一 个 批 处 理 | 


回 


合 是 否 将 要 启动 。 如 果 不 是 ， 它 通过 调用 go () 方法 创建 一 个 新 的 。 它 会 等 待 批 处 理 回合 


站 


在 go () 中 的 await HH\Asio\later () 是 批 处 理 的 关键 所 在 。 对 了 


其 他 希望 做 相关 查询 的 等 待 句柄 来 说 ， 它 的 功能 是 一 个 “最 终 调用 ”。 这 导致 go () 被 推迟 ， 直 到 


他 挂 起 的 等 待 句柄 开始 运行 。 


想 一 人 one () 和 two () 的 例子 。 整 个 过 程 是 从 以 下 这 行 开始 的 : 


$results = await HH\Asio\v (array (one('hello'), twol('world'))); 


one () 和 two () 都 是 挂 起 的 。 设 想 one () 首先 得 到 运行 ， 它 调用 了 lookup () ， 然 后 调用 了 重新 调度 的 go () 。 运 行 时 会 查找 其 他 能 够 运行 的 等 待 句柄 。two () 仍然 是 挂 起 状态 ， 以 便 运行 并 
调用 lookup () ， 然 后 当 它 执行 await self: : $waitHandle 的 时 候 被 暂停 。 (因为 那个 等 待 句柄 已 经 运行 了 。) 


在 此 之 后 ，go () 恢复 并 完成 了 它 的 获取 操作 ， 同 时 返回 它 的 结果 。 所 有 挂 起 的 lookup () 实例 收 到 他 们 的 结果 ， 并 且 把 他 们 传递 回 one () 和 two () 。 


四 “计算 机 的 计算 时 间 总 是 一 个 琼 手 的 问题 。 由 于 各 种 原因 ，HHNAsioNusleep0 的 实际 休眠 时 间 间 隔 可 能 并 不 会 精确 到 微 秒 级 别 。 其 中 一 个 最 重要 的 原因 就 是 “时 钟 ”的 基础 构成 变化 ， 这 和 HHVM 所 处 操作 
系统 及 硬件 环境 都 是 有 关系 的 。 


6.5 ”常见 错误 


6.5.1 丢弃 等 待 句柄 


当 你 调用 一 个 异步 函数 时 ， 它 返回 了 一 个 等 待 句柄 。 当 你 等 待 这 个 等 待 句柄 的 时 候 ， 异 步 函 数 体 将 会 执行 完成 。 但 是 如 果 你 没有 等 待 这 个 等 待 句柄 ， 将 会 发 生 什 么 事情 ? 


async function speak(): Awaitable<void> { 
echo "one"; 
await HH\Asio\later(); 
echo "two"; 
echo "three"; 


} 
async function f(): Awaitable<void> { 


Shandle = speak(); 
// 不 要 等 待 或 者 join， 仅 仅 丢 弃 它 
i 


HH\Asio\join (£()); 


这 个 speak () 函数 将 会 执行 到 什么 程度 ” 换 句 话说 ， 将 会 输出 些 什 么 ? 


可 能 的 答案 就 是 什么 都 没有 、one， 或 者 是 onetwothree。 补 充 来 说， 你 得 到 的 答案 在 每 次 运行 时 候 并 不 能 保证 一 致 的 结果 。 基 于 你 运行 的 HHVM 版 本 的 不 同 ， 这 个 答案 也 可 能 会 不 同 。 其 他 运行 中 的 
异步 函数 的 状态 ， 就 像 那 世 界 另 一 头 的 蝴蝶 扇 着 的 翅膀 。 


这 就 是 说 ， 运 行 时 有 很 大 的 余地 来 决定 该 做 些 什么 。 当 它 遇 到 一 个 await 表 达 式 的 时 候 ， 仅 仅 被 允许 暂停 speak () 的 执行 。 在 这 个 约束 之 内 ， 它 可 能 暂停 然后 恢复 speak () ， 如 此 往返 操作 很 多 次 。 
这 是 给 予 异 步调 度 管理 视 情况 安排 合适 的 异步 执行 的 灵活 性 。 但 是 它 还 意味 着 你 必须 非常 小 心地 等 待 任何 你 创建 的 等 待 句柄 。 等 待 句柄 的 等 待 操作 失败 将 会 导致 不 可 预知 的 行为 。 等 待 一 个 等 待 句柄 将 会 保 


证 它 运 行 完毕 。 


你 可 能 有 冲动 要 做 这 样 的 事情 来 实现 一 个 独立 的 任务 。 这 就 是 说 ， 你 希望 开始 一 个 任务 并 且 让 它 执行 ， 但 是 你 并 不 希望 在 等 待 它 执行 完毕 时 ， 阻 碍 任何 其 他 的 东西 。 异 步 并 不 提供 独立 任务 的 任何 途 
径 。 强 制 一 个 等 待 句柄 运行 的 办 法 就 是 等 待 它 ， 这 里 并 没有 什么 办 法 使 得 等 待 一 个 句柄 时 没有 任何 潜在 的 阻碍 。 


甚至 如 果 你 等 待 你 创建 的 所 有 等 待 句柄 ， 这 仍然 有 可 能 看 到 它们 不 同 顺序 的 效果 。 在 这 个 例子 中 ， 任 何 关于 some_unrelated _stuff () 的 副作用 〈 写 入 输出 缓冲 、 网 络 或 者 磁盘 /O 等 ) 都 可 能 发 生 在 
some async function () 的 副作用 之 前 ， 或 者 之 后 : 


async function f(): Awaitable<void> { 
$handle = some async function(); 
some unrelated stuff(); 
await $handle; 


} 


一 般 来 说 ， 不 鼓励 把 等 待 句柄 的 创建 和 句柄 的 等 待 分 离 。 一 个 等 待 句柄 的 创建 和 等 待 应 该 尽 可 能 在 一 起 。 前 一 个 例子 最 好 写成 这 样 : 


async function f(): Awaitable<void> { 
some unrelated stuff(); 
await some async function(); 


i 


不 要 假设 ， 他 们 会 按 这 个 顺序 发 生 。 因 为 你 已 经 观测 到 了 一 次 “正确 的 ”效果 顺序 了 。 这 个 顺序 可 能 在 两 个 相同 的 代码 的 执行 之 间 发 生变 化 。 为 了 避免 不 得 不 关注 这 个 问题 ， 你 不 要 尝试 编写 有 副 作 
并 且 顺 序 非常 重要 的 异步 函数 。 如 果 你 希望 两 个 事情 按 一 个 特殊 的 顺序 发 生 ， 你 必须 使 用 await 在 他 们 之 间 创建 一 个 依赖 。 


异步 不 创建 线程 


从 Hack 代 码 的 视角 来 看 ， 整 个 世界 都 是 单线 程 的 ， 这 一 点 和 PHP 一 样 。 一 个 异步 苑 数 并 非 一 个 线程 ， 多 重 异 步 函数 并 不 会 并 行 执行 。 单 一 的 PHP/Hack 环 境 的 代码 不 会 运行 在 多 个 CPU 核 心 上 。 (HHVM 
使 用 系统 级 别 线程 来 运行 多 重 网 页 请 求 。 但 是 在 这 些 线程 上 的 PHP/Hack 环 境 并 不 能 实质 性 地 相互 影响 。) 


异步 扩展 可 能 在 幕后 使 用 了 线程 ， 但 这 是 一 个 实现 细节 ， 对 于 Hack 代 码 来 说 完全 不 可 见 。 
当然 ， 有 些 时 候 你 应 该 并 行 地 使 用 线程 。 例 如 ， 当 你 正在 做 CPU 密集 型 的 工作 时 ， 这 些 工作 可 以 分 解 为 很 多 个 任务 ， 任 务 之 间 需 要 彼此 偶尔 进行 同步 。 在 这 些 情况 下 ， 异 步 并 不 会 帮助 你 。 事 实 


上 ，Hack 可 能 并 非 这 份 工作 的 正确 编程 语言 。 


6.5.2 ”异步 函数 备 忘 


因为 异步 函数 被 设计 用 于 耗 时 操作 ， 它 们 天 生 就 适合 搭配 memoization (备忘录 ) 。 备 忘 录 是 个 非常 常见 的 编程 模式 ， 用 于 缓存 一 个 成 本 高 的 操作 结果 ， 以 便 下 次 有 需要 的 时 候 可 以 用 较 低 的 成 本 返 


回 


function time consuming op impl(): string { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


function time consuming op(): string { 
static $result = null; 
if ($result === null) { 

$result = time consuming op impl (); 


return $result; 


特别 属性 _Memoize ( 见 3.6.2 节 的 相关 内 容 ) 应 用 于 异步 函数 时 ， 也 会 正常 生效 。 当 你 希望 使 用 备忘录 时 ， 你 通常 应 该 使 用 这 : 
更 好 的 控制 ) ， 请 接着 往 下 读 。 


> 


属性 。 如 果 你 有 好 的 理由 不 使 用 这 


> 


属性 (例如 ， 需 要 对 备忘录 缓存 做 


当 手工 操作 异步 函数 的 备 忘 功 能 时 ， 你 一 定 要 意识 到 这 里 可 能 有 一 些 潜在 的 严重 错误 ， 会 导致 一 个 “ 竞 态 条 件 (race condition) ”。 需 要 记 住 的 关键 点 是 : 备 忘 等 待 句柄 ， 而 不 是 结果 。 


对 结果 进行 备 忘 是 最 直观 明了 的 事情 ， 像 下 面 这 样 : 


async function time consuming op _ impl() : Awaitable<string> { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 


async function time consuming op(): Awaitable<string> { 
static $result = null; 
if ($result === null) { 
$result = await time consuming op impl(); // 错 误 ! 


} 
return $result; 


} 


这 里 就 产生 了 一 个 “ 竞 态 条 件 ”。 设 想 一 下 这 里 有 另外 两 个 异步 函数 : one () 和 two () ， 它 们 都 存在 于 异步 调度 队列 之 中 ， 并 且 它 们 都 需要 等 待 time_consuming_op () 完成 。 那 么 ， 下 面 的 事件 
序列 将 会 发 生 : 


1.one () 获得 运行 ， 然 后 等 待 time_consuming op () 。 


2:time_consuming_op () 发 现 备忘录 缓存 是 空 的 ($result 是 null) ， 所 以 它 等 待 time_consuming_op_impl () 执行 完毕 。 于 是 它 被 暂停 了 。 


3.two () 获得 运行 ， 并 且 等 待 time_ consuming_op () 。 注 意 这 是 一 个 新 的 等 待 句柄 了 。 这 和 步骤 1 中 的 等 待 句柄 并 非 同一 个 。 


4.time_consuming_op() 再 次 发 现 备忘录 缓存 是 空 的 ， 所 以 它 再 一 次 等 待 time_consuming_op_impl () 。 现 在 这 个 耗 时 操作 将 被 执行 两 次 。 


如 果 time consuming_op_impl () 有 副作用 。 比 如 ， 这 可 能 是 个 数据 库 写 入 操作 。 那 么 这 样 就 可 能 导致 一 个 非常 严重 的 bug。 甚 至 如 果 这 里 并 没有 副作用 ， 这 仍然 是 个 bug。 当 耗 时 操作 仅 需 要 执行 
一 次 ， 它 实际 执行 了 多 次 。 


这 个 bug 的 根源 在 于 在 检查 缓存 和 填充 缓存 的 过 程 中 ，time_consuming_op () 可 能 被 暂停 。 通 过 检查 缓存 发 现 它 是 空 的 ， 这 派生 出 了 一 个 关于 世界 状态 的 事实 : 这 个 操作 还 没有 结束 。 但 是 在 等 待 之 
因为 可 能 被 暂停 ， 这 个 事实 不 再 为 真 : 在 if 代码 段 内 的 不 变量 可 能 被 改变 了 。 
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正如 我 先前 所 说 的 那样 ， 正 确 的 解决 方案 是 对 等 待 句柄 做 备 忘 ， 而 不 是 结果 : 


async function time consuming op(): Awaitable<string> { 
static $handle = null; 
if ($handle === null) { a 
$handle = time_consuming op_impl() ; // 不 要 在 这 里 等 待 ! 
下 
return await $handle; // 改 在 这 里 进行 等 待 


这 可 能 和 直觉 相 违背 ， 因 为 函数 在 每 次 执行 甚至 在 命中 缓存 的 时 候 都 要 等 待 。 但 这 是 个 好 事情 : 在 除 第 一 次 之 外 的 每 次 执行 中 ，$handle 都 不 是 null， 所 以 time_consuming_op_impl () 的 新 实例 并 不 
会 开始 。 已 经 存在 的 那个 实例 的 结果 将 会 被 共享 。 


“ 况 态 条 件 ” 已 经 过 去 了 。 早 期 列 出 的 事件 序列 已 经 不 再 可 能 发 生 : time consuming_op () 在 发 现 缓存 为 空 和 填充 缓存 的 过 程 中 ， 并 不 会 被 暂停 。one () 和 two () 两 个 函数 将 会 等 待 同一 个 等 待 
句柄 : 就 是 在 time_ consuming_op () 中 被 缓存 的 那个 。 这 并 没有 发 生 什么 错误 。 它 们 将 会 等 待 这 个 句柄 完成 。 一 旦 完成 ， 它 们 都 会 收 到 对 应 的 结果 。 


6.6 异步 扩展 


在 本 节 中 ， 我们 将 详细 学 习 HHVM 3.6 中 的 四 个 异步 扩展 ， 分 别 是 MySQL、MCRouter、cURL 和 streams。 


语言 级 别 的 异步 组 件 在 3.6 之 前 的 几 个 版 本 中 已 被 包含 ， 但 是 这 些 扩展 在 3.6 中 是 全 新 的 []。 它 们 中 的 一 些 还 不 是 特性 完成 的 状态 ， 但 是 它们 将 会 在 未 来 版 本 中 得 到 改进 。 


6.6.1 MySQL 


MYSQL 的 异步 扩展 是 个 面向 对 象 的 MYSQL APl， 这 让 人 想起 了 PHP 和 HHVM 中 伴随 发 行 的 mysqli 扩 


池 、 进 行 查 询 以 及 读 取 结果 。 


连接 并 查询 


你 可 以 从 类 AsyncMysqlClient 


class AsyncMysqlClient { 
public static async function connect( 


string $host, 
int $port, 
string $dboname, 
string $user, 
string $password, 


int $timeout micros = -1 
) : Awaitable<?AsyncMysqlConnection>; 


} 


展 。 我 们 在 这 里 并 不 会 面面俱到 。 我 们 只 是 挑 一 些 重点 部 分 进行 讲解 ， 比 如 建立 连接 、 使 


始 学 起 。 它 有 个 静态 异步 方法 叫做 connect () ， 创 建 了 一 个 到 MySQL 数 据 库 的 连接 。 它 的 代码 是 这 样 的 : 


连接 


这 五 个 必需 的 参数 都 是 标准 的 MySQL 连 接 参 数 : 主机 地 址 、 端 口 、 数 据 库 名 称 、 用 户 名 和 密码 。 最 后 一 个 参数 是 可 选 的 : 连接 超时 的 微 秒 数 。 默 认 值 是 - 1， 就 是 说 使 


中 是 1 秒 ) 。 设 置 为 0 就 意味 着 没有 超时 。 


connect () 的 结果 是 一 个 AsyncMysq 
queryf () 。query () 的 参数 是 一 个 包含 查询 的 字符 


queryf () 是 大 多 数 时 候 需 


参 ， 然 后 是 要 对 占 位 符 进行 值 蔡 换 的 替换 实 参 : 


用 到 的 ， 因 为 在 它 的 查询 字符 串 中 可 以 使 


Connection (如 果 在 建立 连接 的 时 候 发 生 错 误 ， 结 果 将 是 个 null) 。AsyncMysqlConnection 有 两 个 异步 方法 


， 以 及 一 个 超时 设置 (和 connect () 的 超时 遵守 一 样 的 规定 ， 但 这 里 的 默认 超时 时 间 是 60 秒 ) 。 


默认 的 超时 设置 (在 HHVM3.6 


于 查询 数据 库 ， 它 们 分 别 是 query () 和 


占 位 符 ， 并 经 过 适当 的 转 义 之 后 ， 这 些 占 位 符 将 会 被 蔡 代 值 蔡 换 。 这 是 一 个 参数 可 变 的 方法 ， 传 递 查询 字符 串 作 为 第 一 个 实 


async function fetch user name (int $user id) : Awaitable<string> { 
$conn = await AsyncMysqlClient::connect( 


的 
3306, 
'example', 
'admin', 
'hunter2', 


if ($conn !== null) 


{ 


$result = await $conn->queryf ( 
'SELECT name FROM user WHERE id = %d', 


$user id 


} 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


如 下 所 示 ， 可 用 占 位 符 的 全 部 范围 是 : 


'， %T: 一 个 表 名 


* %C: 一 个 列 名 


“ %s: 一 个 字符 串 


“ %d: 一 个 整数 


" %f; 一 个 浮 点 数 


“ %=s: nullable 字 符 串 比较 。 如 果 你 传递 了 一 个 字符 串 ， 这 个 将 扩展 为 ='the string'。 如 果 你 传递 的 是 null， 它 将 扩展 为 IS NULL。 


“ %=d: nullable 整 数 比 较 。 


* %=f: nullable 浮 点 数 H 


较 。 


“ %Q: 原始 SQL 语句 。 你 传递 的 字符 串 会 在 不 转 义 的 情况 下 被 替换 。 这 非常 危险 ， 因 为 它 开 启 了 SQL 注入 的 可 能 性 ， 这 可 能 是 个 非常 严重 的 安全 漏洞 。 要 尽 可 能 地 避免 使 用 它 。 


Hack 的 类 型 检查 器 非常 


:雪村 
1 月 眉 


queryf () 查询 字符 串 ， 对 调用 queryf () 的 类 型 检查 ， 可 以 保证 传递 对 正确 的 实 参 个 数 ， 并 且 传递 的 参数 都 具有 正确 的 类 型 : 


async function do_something (AsyncMysqlConnection $conn): Awaitable<void> { 


// 错误 : 实 参 太 少 


$result = await $conn->queryf ('SELECT * FROM user WHERE id = %d'); 


} 


类 型 检查 器 故意 没有 识别 占 位 符 %Q， 目 的 就 是 不 鼓励 使 


在 将 来 的 发 行 版 中 ，queryf () 将 会 支持 更 多 的 占 位 符 类 型 ,例如 %L 家 族 (%Ld 用 于 整 型 列表 ，%Ls 


连接 池 


AsyncMysqlConnection 的 一 个 重要 约束 就 是 : 你 不 能 
就 是 一 个 可 重用 连接 对 象 的 集合 。 当 一 个 客户 端 从 池子 里 面 请 求 一 个 连接 时 ， 它 可 能 得 到 已 经 存在 的 一 个 连接 ， 这 将 避免 达到 创建 一 个 新 连接 的 总 开销 。 


于 字符 串 列表 等 ) 。 


单一 的 连接 上 并 行 做 多 个 查询 。 然 而 这 是 当 你 使 


异步 的 时 候 经 常 想 做 的 


它 。 如 果 你 真 的 需要 使 用 它 ， 你 可 以 使 用 HH_FIXME 注 释 来 隐藏 这 个 错误 ( 详 见 3.11 节 ) 。 


有 有情 。 解 决 方案 就 是 使 用 AsyncMysqlConnectionPool。 一 个 连接 池 


人 A、 在 HHVM 早 于 3.6.3 的 版 本 中 ， 连接 池 有 个 重大 的 bug， 可 能 会 导致 虚假 的 超时 。 如 果 你 使 用 连接 池 的 话 ， 请 确保 你 使 用 的 是 HHVM 3.6.3 或 者 更 新 的 版 本 。 


可 以 像 下 面 这 样 创建 一 个 连接 池 : 


$pool = new AsyncMysdqlConnectionPool (array()) 7 


构造 器 有 一 个 实 参 ， 这 是 个 配置 选项 的 数组 。 可 能 的 选项 值 是 : 


per_key_conne ction_limit 


在 池子 中 ， 对 于 “服务 器 名 、 端 口号 、 数 据 库 及 用 户 名 ”所 允许 的 最 大 连接 数 。 默 认 值 是 50。 


pool_connection_limit 

池子 中 所 人 允许 总 的 连接 数量 。 默 认 值 为 5000。 

idle_timeout_mictros 

在 连接 池 中 ， 一 个 连接 在 被 销毁 前 允许 保持 空闲 的 最 大 微 秒 数 。 默 认 值 为 4 秒 。 
age_timeout_micros 

在 连接 池 中 ， 一 个 连接 在 被 销毁 前 允许 达到 的 最 大 周期 微 秒 数 。 默 认 值 为 60 秒 。 


expiration_policy 


一 个 字符 串 ， 或 者 IdleTime' ， 或 者 ,Age'。 它 用 于 指明 池 中 的 连接 将 依据 闲置 时 间 还 是 周期 被 销毁 。 默 认 值 为 Age 。 


例如 ， 创 建 一 个 连接 池 ， 相 关 选 项 为 最 多 100 个 连接 ， 并 且 过 期 策略 是 空闲 时 间 : 


$pool = new AsyncMysqlConnectionPool ( 
array( 
"Pool_connection limit' => 100, 
'expization policy' => 'IdleTime', 
) 
); 


一 旦 你 创建 了 一 个 连接 池 ， 你 可 通过 调用 和 等 待 它 的 异步 方法 connect () 来 获得 连接 。 所 需要 的 实 参 列表 和 你 传递 给 AsyncMysqlConnection: : connect () 的 实 参 列表 完全 一 样 。 


<<_ Memoize>> 

function get pool(): AsyncMysqlConnectionPool { 
return new AsyncMysqlConnectionPool ([]); 

} 


async function get connection(): Awaitable<?AsyncMysqlConnection> { 
return await get pool () ->connect ( 
+127:0,.0:1"s 
3306, 
"example'y 
"admin'y 
'hunter2', 


query () 和 queryf () 的 结果 都 是 类 AsyncMysqlResult 的 实例 。 这 是 一 个 抽象 类 ， 它 的 两 个 非常 重要 的 具体 子 类 就 是 AsyncMysqlQueryResult 和 AsyncMysqlIErrorResult。 


AsyncMysqlQueryResult 有 四 个 用 于 获得 结果 的 非 异步 方法 : mapRows () 、vectorRows () 、mapRowsTyped () 和 vectorRowsTyped () 。 所 有 这 四 个 方法 都 会 返回 数据 行 的 一 个 Vector。 
“map” 和 “vector” 部 分 代表 着 每 一 行 是 如 何 表示 的 。MapRows () 和 mapRowsTyped () 将 会 把 数据 行 作为 Map 进 行 返回 ， 其 中 列 名 称 映 射 着 值 。vectorRows () 和 vectorRowsTyped () 会 把 结 
果 数 据 行当 作 Vector 进 行 返回 ， 按 着 查询 中 所 指明 的 顺序 包含 相关 的 值 。 例 如 : 


async function fetch user name (AsyncMysqlConnection $conn, 
> int $user id) : Awaitable<string> { 
$result = await $conn->queryf ( 
'SELECT name FROM user WHERE id = %d', 
$user_ id 


) 


invariant ($result->numRows () =—= 1, 'exactly one row in result'); 


map = $result->mapRows (); 


Smap 
// 你 所 要 的 结果 是 Smap [name'] 


$vector = $result->vectorRows () 7 
return $vector[0]; 


方法 名 中 的 “typed” 表 示 如 何 根据 非 字符 串 列 的 类 型 表示 相关 的 值 。 例 如 ， 如 果 你 有 一 个 列 在 SQL 被 定义 为 整 型 ，mapRowsTyped () 和 vectorRowsTyped () 将 会 从 Hack 的 列 中 返回 整形 值 。 鉴 
于 此 ，mapRows () 和 vectorRows () 将 会 从 同样 的 整形 列 中 返回 字符 串 类 型 值 。 


如 果 这 个 查询 导致 一 个 错误 ，query () 或 者 queryf () 的 结果 将 会 是 一 个 AsyncMysqIErrorResult 对 象 。 这 个 类 有 三 个 重要 的 非 异步 方法 ， 用 于 检查 具体 发 生 了 什么 事情 : 
failureType () 


将 返回 TimedOut' 或 者 'Failed 这 两 个 字符 串 之 中 的 一 个 。 后 者 表示 除 超时 外 的 任何 错误 。 


mysql_errno () 
针对 这 个 问题 ，MySQL 给 出 的 数字 错误 码 。 


mysqgl_error () 


于 描述 这 个 问题 的 人 类 可 识别 的 字符 串 。 


步 MySQL 扩 展 的 相关 更 新 文档 可 以 在 HHVM 官 方 网 站 上 查询 。 


6.6.2 MCRouterffmemcached 


MCRouter (https://github.com/facebook/mcrouter) 是 个 由 Facebook 开 发 的 开源 项 目 。 它 是 个 memcached 协 议 路 由 库 ， 提 供 了 大 量 的 特性 ， 用 于 帮助 扩展 一 个 nemcached 的 相关 部 署 : 连接 
池 、 基 于 前 缀 的 路 由 、 在 线 配置 修改 ， 以 及 更 多 的 特性 。 它 在 客户 端 和 memcached 实 例 之 间 进 行 数 据 沟通 的 时 候 使 用 memcached 的 ASClI 协 议 。 


关于 MCRouter 如 何 使 用 问题 的 深入 探讨 已 经 超出 了 本 书 的 范围 。 在 这 里 ， 我 们 将 会 简单 地 把 MCRouter 类 库 作为 一 个 memcached 客 户 端 来 使 用 MCRouter 扩 展 酷似 PHP 和 Hack 中 的 Memcache 和 
Memcached 扩 展 [。 对 于 memcached 和 MCRouter 自 身 所 支持 的 操作 (cas 或 者 “比较 和 交换 (compare-and-swap) ”， 成 为 了 重大 遗漏 之 一 ) ，MCRouter 扩 展 并 不 全 部 支持 ， 但 是 这 种 情况 在 将 来 


的 发 行 版 本 中 将 会 得 到 改善 。 


这 个 扩展 是 围绕 类 MCRouter 展 开 的 ， 代 表 了 一 个 memcached 客 户 端 。 这 里 有 两 种 方式 获得 一 个 MCRouter 对 象 : 通过 构造 函数 (更 灵活 些 ) ， 或 者 通过 一 个 静态 方法 createSimple () (更 方便 
些 ) 。 这 些 都 是 明显 特征 : 


class MCRouter { 
public function _ construct (array<string, mixed> $options, string $pid = ''); 
public static function createSimple (ConstVector<string> $servers): MCRouter; 


} 


基于 $pid (持久 化 ID) 是 否 为 空 ， 这 个 构造 函数 将 会 有 不 同 的 行为 方式 。 如 果 $pid 为 空 ， 构 造 函数 将 启动 一 个 临时 的 客户 端 ， 并 且 返 回 一 个 对 象 代表 它 。 如 果 $pid 不 为 空 ， 这 个 扩展 将 会 用 这 个 持久 化 
1D 查 找 一 个 已 经 存在 的 客户 端 ， 若 找到 ， 则 返回 它 。 如 果 没 有 找到 的 话 ， 它 将 会 使 用 这 个 持久 化 1D 启 动 一 个 新 的 客户 端 。 一 般 来 说 ， 临 时 客户 端 应 该 只 用 于 调试 和 测试 中 ， 而 不 是 生产 中 。 


$options 参 数 用 于 配置 任何 新 启动 的 客户 端 。 它 必须 拥有 'config_str' 或 者 'config file 这 两 个 键 中 的 一 个 。 其 中 前 者 'config_str 映射 到 一 个 JSON 格 式 的 配置 字符 串 ， 而 后 者 'config_file 将 映射 到 一 个 
包含 JSJON 格 式 配 置 字符 串 的 文件 路 径 上 。 关 于 如 何 配置 MCRouter 的 更 多 信息 ， 请 参见 它 在 GitHub 上 面 的 源码 库 (https://github.com/facebook/mcrouter) 。 


MCRouter: : createSimple () 是 一 个 用 于 创建 客户 端的 简化 方式 。 你 可 以 把 一 个 由 字符 串 组 成 的 Vector ( 见 第 5 章 ) 简单 地 传递 给 它 ， 其 中 包含 memcached 的 运行 服务 器 地 址 信息 。 字 符 串 的 组 成 
是 : 主机 名 ， 紧 接着 冒号 ， 然 后 是 端口 号 。 例 如 '127.0.0.1: 11211 。 


这 个 类 MCRouter 拥 有 的 异步 方法 名 称 ， 和 memcached 的 ASCIlIl 协 议 中 的 名 称 都 是 对 应 的 。 当 失败 的 时 候 ， 它 们 会 抛 出 异常 (这 就 包含 着 一 些 类 似 “ 得 到 了 一 个 根本 不 存在 的 键 ”之 类 的 事情 ) ， 所 以 
来 自 asio-utilities 的 HH\Asio\wrap () 在 这 个 API 就 会 被 派 上 用 场 。 例 如 : 


function fetch user name (MCRouter $mcr, int $user jid) : Awaitable<string> { 
Skey = 'name:' . $user id; 
$cached result = await HH\Asio\wrap ($mcr->get ($key)); 


if ($cached result->isSucceeded()) { 
return $cached result->getResult(); 


| 
// 调头 回来 查询 数据 库 


// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


这 里 有 一 些 异步 方法 用 于 一 些 核心 的 memcached 协 议 命 令 : 


-get () 用 于 读 取 给 定 键 的 值 。 
. set () 用 于 写 入 一 个 值 ， 对 于 给 定 的 键 来 说 ， 如 果 这 个 值 存在 ， 将 会 覆盖 它 。 

add () 用 于 写 入 一 个 值 ， 对 于 给 定 的 键 来 说 ， 如 果 这 个 值 存在 ， 将 会 导致 操作 失败 。 

:replace () 用 于 写 入 一 个 值 ， 对 于 给 定 的 键 说 ， 如 果 这 个 不 存在 的 话 ， 将 会 导致 操作 失败 。 
.append () 和 prepend () 对 于 给 定 的 键 将 把 数据 附加 到 值 的 后 面 (append) 或 者 前 面 (prepend) 。 
incr () 用 于 自动 增长 一 个 数值。 

.del () 用 于 删除 一 个 键 。 


' vetsion () 用 于 获得 远程 服务 器 的 版 本 。 


关于 异步 MCRouter 扩 展 的 更 新 文档 ， 请 参见 HHVM 官 网 (docs.hhvm.com/manual/en/book.hack.mcrouter.php) 。 


663 CURL 


cURL 是 一 个 类 库 ， 用 于 通过 URL 传 送 或 者 获取 资源 数据 。 在 具体 实践 中 ， 它 更 多 地 用 于 创建 HTTP 和 HTTPS 请 求 。 


Hack 中 的 异步 cURL APl 是 由 两 个 函数 组 成 的 : 


async function curl multi await (resource $mh, float $timeout = 1.0) 
: Awaitable<int>; 


namespace HH\Asio { 
async function curl exec (mixed $urlOrHandle): Awaitable<string>; 


} 


HH\Asio\curl_exec() 是 在 curl_multi_await () 基础 上 做 的 一 个 简单 包装 。 你 可 以 传递 给 它 一 个 cURL 句柄 (例如 ,从 curl_init () 中 返回 的 东西 ) ， 或 者 包含 着 一 个 URL 的 字符 串 (这 种 情况 下 ， 它 
将 会 为 你 自动 创建 cURL 句柄 ) 。 然 后 它 将 异步 地 执行 这 个 cURL 句柄 ， 并 且 返 回 它 的 结果 。 


curl_multi await () 是 curl_multi_select () 的 异步 等 价 版 本 。$mh 必 须 是 一 个 CURL 多 重 句柄 (例如 ， 从 curl_multi_init () 中 返回 的 东西 ) ，curl_multi_await () 会 一 直 等 待 ， 直 到 作为 $mh 一 部 
分 的 任意 句柄 上 有 活动 为 止 。 当 它 完成 后 ， 就 表示 至 少 在 一 个 cURL 句柄 上 面 ， 曾 经 有 活动 。 你 通过 用 curl_multi_exec () 执行 它 ， 就 像 你 在 非 异 步 代 码 里 面 所 做 的 那样 。 


这 是 最 简单 的 一 个 异步 扩展 。 它 包含 一 个 单一 函数 ， 叫 做 stream_await () 。 函 数 的 工作 就 是 等 待 ， 直 到 一 个 流 变 得 可 读 或 者 可 写 : 


async function stream await (resource $fp, int $events, float $timeout = 0.0) 
: Awaitable<int>; 


stream_await () 有 三 个 参数 : 
“ $fp 是 用 于 监控 变化 的 流 。 它 的 背后 必须 是 一 个 正常 的 文件 、socket、tempfile 或 者 管道 (pipe) 。 内 存 流 (memory stteam) 和 用 户 流 (user stream) 是 不 支持 的 。 


“ $events 是 全 局 常量 STREAM_AWAIT READ 或 者 STREAM_AWAIT WRITE 中 的 某 一 个 ， 或 者 通过 位 或 运算 表示 它们 两 个 。 它 表示 在 这 个 流 中 要 监控 的 变化 种 类 。 这 就 是 说 ， 或 者 监控 它 变 得 可 读 了 


(例如 ， 这 个 流 上 的 fread () 将 不 会 拦截 ) ， 或 者 可 写 了 《例如 ， 这 个 流 上 的 fwtite () 将 不 会 拦截 ) 。 注 意 ， 一 个 文件 尾部 的 流 将 会 被 认为 可 读 ， 因 为 fread () 不 会 拦截 。 
: Stimeout 是 需要 等 待 的 最 大 时 间 ， 单 位 为 秒 。 如 果 设置 为 零 ， 这 个 异步 函数 将 会 迅速 完成 ， 这 仅 是 个 流 的 状态 查询 。 
函数 的 结果 是 个 整 型 ， 指 明了 流 的 当前 状态 ， 将 映射 到 下 面 四 个 全 局 变量 之 一 : 


“STREAM_AWAIT_ CLOSED 表 明 这 个 流 现在 关闭 了 。 


“STREAM_AWAIT _ READY 表明 这 个 流 现 在 可 读 或 者 可 写 (取决 于 $events 传 入 的 是 什么 值 ) 。 
:STREAM _AWAIT TIMEOUT 表 明 这 个 流 和 以 前 的 状态 一 致 ， 但 是 触发 了 超时 。 


: STREAM_AWAIT ERROR 表明 发 生 了 一 个 错误 。 


stream_await () 和 stream_select () 在 功能 上 是 很 相似 的 ， 等 待 一 个 流 然后 进入 一 个 感 兴趣 的 状态 ， 但 是 它 没有 stream_select () 的 复 用 功能 。 你 可 以 使 用 HH\Asio\v() 来 同时 等 待 多 个 流 的 等 


待 句柄 ， 但 是 合并 结果 的 等 待 句柄 并 不 会 完成 ， 直 到 所 有 组 成 的 流 等 待 句柄 完成 。 你 可 以 在 另外 一 个 使 用 流 结果 的 异步 函数 中 ， 通 过 对 stream_await () 的 调用 进行 包装 ， 完 成 相关 工作 : 


async function read all (array<resource> $fps): Awaitable<void> { 
$read single = async function (resource $fp) { 
$status = await stream await ($fp, STREAM AWAIT READ, 1.0); 


if ($status = STREAM AWAIT READY) { 
// 从 流 读 取 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 
}; 


await HH\Asio\v (array map ($read single, $fps)); 


四 异步 在 Facebook 内 部 已 经 广泛 使 用 了 一 段 时 间 ， 但 使 用 的 是 仅 供 内 部 的 异步 组 件 。 
[中 谈 及 memcached， 会 涉及 两 个 扩展 。Memcached 扩 展 是 较 新 的 一 个 ， 它 支持 更 多 memcached 特 性 ， 所 以 我 们 推荐 使 用 Memcached。 


第 7 章 XHP 


XHP (类 似 XHTML 命 名 方式 ) 是 Hack 的 一 个 特性 ， 它 允许 编程 人 员 借 助 于 嵌入 式 XML 类 似 的 语法 ， 把 一 个 HTML 树 描述 为 PHP/Hack 对 象 。 在 Web 应 用 中 ， 它 消除 了 整个 种 类 的 错误 ， 以 及 安全 漏 


的 来 源 。 它 使 得 UI 代码 更 整洁 、 更 易于 维护 ， 也 更 加 灵活 。 


在 传统 的 PHP 中 ， 你 在 网 页 中 输出 可 能 通过 下 面 两 种 方式 之 一 ， 或 者 使 用 混合 HTML 的 PHP 模 板 : 


<tt>Hello <strong><?= $user name ?></strong>!</tt> 


型 


或 者 通过 字符 串 连 接 或 者 字符 串 插 入 来 输出 : 


echo "<tt>Hello <strong>$user name</strong>!</tt>"; 


有 了 XHP， 上 面 的 例子 可 能 看 起 来 是 这 样 的 : 


echo <tt>Hello <strong>{$user name}</strong></tt>; 


这 是 一 个 非常 普通 的 echo 语 句 ， 并 且 没 有 任何 引号 。 这 种 类 似 HTML 的 语法 是 整个 XHP 语 法 体系 中 的 一 部 分 。 


XHP 对 于 一 个 现代 的 、 面 向 对 象 的 Web 应 用 UI 库 是 一 个 非常 好 的 基石 。 在 本 章 的 学 习 中 ， 我 们 将 会 看 到 你 为 什么 应 该 使 用 它 ， 怎 么 使 用 它 ， 如 何在 它 的 基础 上 进行 构建 ， 还 有 如 何 使 


代码 库 进 行 改造 。 


7.1 为 什么 使 用 XHP 


XHP 可 以 帮助 提高 你 UI 代码 的 安全 性 及 正确 性 ， 它 有 着 大 量 方法 用 于 防止 你 犯 常见 的 错误 。 它 还 可 以 通过 对 你 的 HTML 标 记 提供 一 个 面向 对 象 的 接口 ， 帮 助 你 更 稳健 地 组 织 你 的 代码 。 


7.1.1 ”运行 时 验证 


你 能 够 发 现 以 下 这 段 代 码 中 的 问题 吗 ? 


它 对 一 个 传统 的 


echo '<div class="section-header">'; 
echo '<a href="#intro">Intro to <span class="metal">Death Metal</sapn></a>'; 
echo '</div>'; 


XHP 消 除了 这 一 类 错误 。 上 例如 果 在 XHP 中 (包含 着 错误 的 拼写 ) ， 将 会 是 这 样 的 : 


其 中 一 个 结束 标记 拼写 错 了 : </sapn> 。 在 实际 的 代码 中 ， 直 到 你 在 一 个 浏览 器 中 的 结果 页 面 查看 ， 才 可 能 发 现 这 样 的 一 个 bug。 甚 至 于 你 可 能 根本 没有 注意 到 它 。 这 一 切取 决 于 bug 本 身 。 


echo 
<div class="section-header"> 
<a href="#intro">Intro to <span class="metal">Death Metal</sapn></a> 
</div>; 


当 你 试图 运行 include 或 者 require 这 个 文件 ， 你 将 会 得 到 一 个 致命 错误 : 


Fatal error: XHP: mismatched tag: 'sapn' not the same as 'span' in 
/home/oyamauchi/test.php on line 


XHP 还 提供 了 更 加 精妙 的 验证 形式 。HTM1L 拥 有 规则 用 于 管理 标记 之 间 的 允许 关系 ， 类 似 于 下 面 的 问题 : 哪 一 个 标记 内 部 允许 出 现 其 他 标记 ， 什 么 样 的 标记 人 允许 内 部 是 文本 而 非 其 他 标记 。XHP 可 以 检 
查 这 些 约束 ， 如 果 哪 里 有 违反 ， 则 会 产生 一 个 错误 信息 。 


例如 ， 下 面 的 代码 就 不 是 合法 的 HTML 代 码 ， 因 为 在 <select> 标 记 内 不 允许 出 现 <option> 和 <optgroup> 之 外 的 代码 : 


<select><strong>bold text!</strong></select> 


如 果 你 试图 在 XHP 中 运行 这 些 代码 ， 你 将 会 得 到 一 个 致命 错误 ， 它 会 对 错误 的 位 置 及 类 型 进行 具体 描述 : 


Fatal error: Element “select ”was rendered with invalid children. 
/home/oyamauchi /test .php:2 

Verified 0 children before failing. 

Children expected: 

(:option| :optgroup)* 


Children received: 
:strong 


Ml 


XHP 对 HTML5 草 案 中 推行 的 很 多 规则 都 做 了 验证 ， 但 并 非 是 全 部 。 当 你 定义 类 来 扩展 XHP 的 时 候 ， 你 可 以 为 它们 添加 验证 规则 。 我 们 将 在 7.3.2 节 进行 具体 学 


7.1.2 ”默认 安全 


这 里 有 一 些 代 码 应 用 于 网 站 表单 提交 。 使 用 者 在 表单 输入 项 目 内 输入 她 的 名 字 ， 然 后 这 个 页 面 将 展示 一 个 个 性 化 的 欢迎 信息 。 这 里 有 什么 问题 呢 ? 


$user name = $ REQUEST['name']; 


echo '<html>'; 

echo '<head><title>Welcome</title></head>'; 

echo '<body>Welcome, ' . $user name . '</body>'; 
echo '</html>'; 


这 里 有 个 安全 漏洞 。 如 果 用 户 提交 了 一 个 包含 HTML 标 记 的 字符 串 ， 这 个 标记 将 被 浏览 器 解释 为 文档 对 象 模型 (DOM) 的 一 部 分 。 例 如 ， 如 果 用 户 在 name 查 询 参 数 里 面 提 交 了 
<blink>blinkytext</blink>， 将 会 在 结果 页 面 上 有 个 不 停 闪烁 的 文本 ， 这 显然 不 是 网 站 作者 想 看 到 的 。 这 个 问题 还 称 为 跨 站 脚本 攻击 (cross-site scripting vulnerability，XSS) 【1], 


如 果 没 有 XHP， 这 种 XSS 攻 击 需 要 添加 一 个 对 函数 htmlspecialchars () 的 调用 来 进行 修复 : 


$user _name = htmlspecialchars ($_REQUEST[ ‘name']); 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


这 仍然 很 麻烦 : 你 必须 记 住 为 每 一 个 可 能 包含 用 户 输入 项 目的 字符 串 进 行 转 义 (包含 从 数据 库 查 询 得 到 的 结果 ) 。 你 还 必须 确保 它们 只 转 义 了 一 次 ， 否 则 ， 你 可 能 会 遇 到 双重 转 义 的 bug， 这 并 不 是 什 
么 安全 漏洞 ， 但 仍然 是 不 推荐 的 。 


这 个 例子 很 容易 修复 ， 但 还 是 特别 令 人 震惊 。 在 真实 的 代码 中 ，XSS 攻 击 更 加 精妙 。 大 多 数 代码 库 都 会 有 大 量 的 函数 或 者 方法 输出 一 个 完整 的 Web 页 面 的 片段 ， 并 且 它 们 在 很 多 不 同 的 层次 被 调用 ， 来 
组 成 最 终 的 页 面 。 确 保 所 有 必要 的 转 义 只 做 一 次 ， 对 于 所 有 的 层次 来 说， 都 是 非常 困难 和 精妙 的 任务 。 


这 里 有 些 XHP 中 类 似 的 代码 : 


$user name = $ REQUEST['name']; 

echo 
<html> 
<head><title>Welcome</title></head> 
<body>Welcome, {$user name}</body> 
</html>; 


这 里 并 没有 任何 对 htmlspecialchars () 函数 的 调用 ,或 者 其 他 转 义 程序 ， 但 是 这 里 并 没有 XSS 漏 洞 。XHP 输 出 一 个 字符 串 之 前 ,会 把 里 面 的 保留 字符 转 义 为 HTML 实 体 。 例 如 ,会 把 < 蔡 换 为 &lt; 。 


这 个 问题 的 根源 在 于 : PHP 和 Hack 对 于 原始 字符 串 和 HTML 字 符 串 并 没有 区 别 对 待 。 最 好 认为 它们 是 两 个 完全 不 同 的 数据 类 型 ， 然 后 使 用 特殊 的 逻辑 在 它们 之 间 进 行 转化 。 一 个 原始 字符 串 意味 着 原样 
输出 。 而 一 个 HTML 字 符 串 是 一 个 序列 化 的 DOM 树 ， 意 味 着 用 做 HTML 泻 染 引擎 的 输入 项 。 


XSS 漏 洞 源 自 于 把 原始 字符 串 误 当 作 HTML 字 符 串 进行 对 待 。 用 户 在 表单 项 目 中 输入 的 这 个 字符 串 是 个 原始 字符 串 ， 所 以 它 必须 在 被 一 个 HTML 演 染 引擎 当 作 输 入 项 之 前 ， 转 化 为 一 个 HTML 字 符 串 ( 保 
留 HTML 字 符 必须 被 转 义 ) 。 如 果 任 务 失 败 了 ， 原 则 上 来 说 就 是 一 个 类 型 错误 。XHP 通 过 缓解 你 对 处 理 HTML 字 符 串 的 需求 以 彻底 解决 这 个 问题 。 


把 HTML 想 象 成 一 种 序列 化 的 格式 ， 而 不 是 一 种 标记 语言 ， 将 使 问题 变 得 更 加 清晰 。 对 比 另外 一 种 常用 的 序列 化 格式 JSON。 当 你 编写 一 段 将 要 输出 JSON 的 代码 时 ， 你 并 不 会 去 手工 组 装 JSON 字 符 串 。 
而 是 使 用 PHP/Hack 对 象 或 者 数组 来 建立 对 应 的 结构 ， 并 在 最 后 一 步 使 用 son_encode () 函数 把 它 序列 化 为 JSON。 你 作为 程序 开发 人 员 ， 绝 对 不 会 直接 处 理 包含 JSON 编 码 数据 的 字符 串 。 


类 似 地 ，XHP 将 会 给 你 一 个 方式 来 使 用 PHP 或 Hack 对 象 构建 一 个 结构 体 ， 然 后 把 它 序列 化 为 HTML， 而 不 是 直接 处 理 一 个 序列 化 的 HTML 字 符 串 ， 除 非 把 输出 为 流 。 


为 什么 XSS 是 危险 的 ? 
对 XSS 漏 洞 的 全 面 探索 已 经 超出 了 本 书 的 范围 ， 但 是 这 里 有 个 简要 的 预览 。 以 XSS 身 份 出 现 的 最 紧 的 危险 就 是 : 它 允 许 攻击 者 在 用 户 信任 的 网 站 上 下 文中 ， 执 行 恶 意 的 JavaScript 代 码 。 


一 个 浏览 器 中 运行 的 JavaScript 代 码 ， 通 常 可 以 获得 其 他 窗口 和 同一 个 浏览 器 其 他 tab 中 的 信息 ， 但 是 前 提 是 它们 显示 的 都 是 同一 个 网 站 。 在 这 种 情况 下 ， 如 果 你 在 一 个 tab 中 开 着 你 的 银行 网 站 ， 然 后 另外 
一 个 tab 打 开 一 个 恶意 网 站 ， 恶 意 网 站 的 JavaScript 代 码 并 不 能 访问 你 的 银行 信息 。 这 种 限制 称 之 为 同 源 策 略 。 


然而 ， 如 果 银 行 网 站 存在 一 个 XSS 漏 洞 ， 攻 击 者 可 能 利用 它 执行 自己 设计 好 的 JavaScript 代 码 ， 因 为 这 个 银行 网 站 已 经 提供 了 相关 的 漏洞 条 件 。 对 应 的 恶意 JavaSctipt 将 会 访问 到 银行 网 站 的 DOM， 甚 至 更 
多 。 例 如 ， 向 攻击 者 控制 的 网 站 发 起 一 个 包含 你 银行 卡号 的 HTTP 请 求 。 


[由 这 里 并 不 是 CSS， 因 为 CSS 是 Cascading Style Sheets。 


7.2 如 何 使 用 XHP 


HHVM 内 置 了 对 XHP 的 支持 。 你 可 以 使 用 配置 项 目 hhvm.enable_xhp 来 对 它 进 行 开启 和 关闭 。 你 可 以 在 不 开启 任何 其 他 Hack 特 性 的 前 提 下 开启 XHP 特 性 。 


你 可 能 还 需要 XHP 的 Hack 库 。 它 包含 了 形成 XHP 基 础 设施 的 类 ， 还 包括 HTML5 所 支持 的 标记 对 应 的 类 。 为 了 把 它 整 合 进 你 的 项 目 ， 推 荐 使 用 Composer。 它 将 会 致力 于 从 源头 获取 代码 ， 然 后 设置 自动 
加 载 关联 类 库 ， 这 样 你 就 能 够 立即 使 用 XHP 了 。 


对 Composer 使 用 的 完整 介绍 已 经 超出 了 本 书 的 范围 ， 但 是 这 里 有 段 代码 ， 需 要 添加 到 你 项 目 里 面 的 composerjson 文 件 中 : 


"require": { 
"facebook/xhp-lib": "~2.2" 
} 


这 段 话 指明 了 我 们 需要 XHP 是 2.2 或 者 更 新 版 本 。 


7.2.1 基本 标记 使 用 


我 们 已 经 看 到 了 很 多 个 关于 XHP 使 用 的 例子 ， 但 是 在 这 里 ， 我 们 将 会 从 最 基本 的 开始 讲 起 。 


XHP 是 创建 XHP 对 象 的 一 种 语法 。XHP 对 象 只 是 和 其 他 的 Hack 对 象 非常 类 似 : 例如 ， 你 可 以 在 它们 之 上 调用 方法 ， 如 果 你 传递 一 个 人 HP 对 象 到 内 置 函数 js_object () ， 它 将 会 返回 true。 唯 一 的 区 别 就 
在 于 ,创建 一 个 XHP 对 象 并 不 使 用 关键 词 hew， 而 是 使 用 XHP 标 记 。XHP 标 记 是 一 个 类 似 HTML 的 语法 扩展 。 


XHP 对 象 是 XHP 类 的 实例 ，XHP 类 和 其 他 的 Hack 类 非常 类 似 ， 除 了 以 下 两 点 : 它们 的 名 字 都 以 一 个 冒号 (: ) 开始 ， 这 在 PHP 和 Hack 中 都 是 非法 的 ; 它们 都 是 来 自 XHP 核 心 库 类 : xhp 的 后 裔 ， 当 然 可 
能 并 非 是 直接 后 裔 。 


XHP 对 象 是 为 了 组 成 一 个 树 结构 。 每 一 个 对 象 都 可 以 拥有 任意 数量 的 子 元 素 ， 任 意 子 元 素 都 或 者 是 文本 ， 或 者 是 另外 一 个 XHP 对 象 。 这 对 应 着 HTML 文 档 的 结构 。 


在 它 的 最 基础 的 部 分 ，XHP 标 记 语法 组 成 是 : 一 个 不 包括 开头 冒号 的 XHP 类 名 ， 包 裹 在 一 对 尖 括 号 内 (< 和 >) 。 这 个 是 开始 标记 。 每 一 个 开始 标记 都 必须 对 应 一 个 结束 标记 ， 它 的 组 成 是 : 同样 的 类 
名 ， 以 一 个 斜 线 为 前 缀 ， 然 后 全 部 包裹 在 尖 括 号 里 面 。 在 开始 标记 和 结尾 标记 之 间 可 以 是 文本 ， 也 可 以 是 其 他 标记 ， 或 者 谋 入 的 Hack 代 码 ( 见 7.2.3 节 的 内 容 ) 。 


这 个 例子 创建 了 一 个 简单 的 XHP 对 象 ， 它 是 类 : strong 的 一 个 实例 ， 然 后 把 它 作为 一 个 实 参 传递 给 echo 语 句 。 它 有 一 个 子 元 素 ， 就 是 字符 串 bold text: 


echo <strong>bold text</strong>; 


这 里 有 个 更 为 复杂 的 例子 ， 用 于 创建 一 个 类 : div 的 XHP 对 象 ， 这 个 XHP 对 象 拥有 两 个 子 元 素 。 第 一 个 子 元 素 是 字符 串 plain text。 第 二 个 子 元 素 是 类 : strong 的 XHP 对 象 实现 。 它 有 一 个 子 元 素 就 是 字 
符 串 bold text: 


echo 
<div> 
plain text 
<strong>bold text</strong> 
</div>; 


从 本 例 中 可 以 学 到 的 最 重要 的 事情 就 是 ，XHP 中 的 空白 字符 不 很 重要 。 在 XHP 内 部 的 文本 中 ， 任 何 空白 字符 的 序列 (空格 、tab、 换 行 以 及 回 车 ) 都 将 被 压缩 为 一 个 空格 。 本 例 中 ， 我 们 允许 换行 和 缩 进 
风格 的 使 用 ， 这 是 我 们 对 于 不 适合 在 单一 行 上 的 XHP 代 码 所 推荐 的 风格 。 


请 记 住 ， 语 法 是 为 了 描述 一 个 结构 树 。 为 了 确保 它 这 样 做 ， 开 始 和 结束 标记 都 必须 恰当 地 进行 谋 套 。 这 就 是 说 ， 如 果 你 有 一 系列 的 开始 标记 ， 它 们 所 对 应 的 结束 标记 都 必须 以 相反 的 顺序 出 现 。 例 如 ， 
这 里 有 个 不 合法 的 语句 : 


echo <strong><em>bold italic text</strong></em>; 


开始 标记 <em> 在 <strong> 标 记 内 部 ， 但 是 结束 标记 </em> 却 在 </strong> 之 外 。 这 就 打破 了 树 形 结构 : 树 上 的 一 个 节点 不 能 够 部 分 属于 另外 一 个 节点 的 子 节点 ， 而 部 分 不 属于 。 在 本 例 中 ， 结 束 标 
记 </em> 必 须 置 于 结束 标记 </strong> 之 前 。 很 多 Web 浏 览 器 的 HTML 泻 染 引 擎 对 于 这 种 错误 是 容忍 的 ， 但 是 XHP 并 不 行 。 


标记 也 可 以 是 自 闭合 的 ， 这 就 相当 于 在 一 个 开始 标记 后 面 ， 立 刻 跟 了 一 个 它 的 结束 标记 。 这 通常 用 于 没有 子 元 素 的 XHP 对 象 。 和 HTML 中 一 样 ， 自 闭合 的 标记 的 语法 是 : 在 结束 的 尖 括 号 之 前 立即 添加 
一 个 斜 线 。 斜 线 之 前 的 空格 不 是 必需 的 ， 包 含 空格 仅仅 是 个 文体 上 的 选择 : 


echo <hr />; 


HTML 字 符 引 用 


作为 一 个 简单 
字符 时 ， 这 将 非常 有 用 。 


也 
中 


面 量 字符 的 可 选项 ，HTML 字 符 引用 是 一 条 在 HTML 中 进行 字符 编码 的 方法 。 当 你 需要 对 像 & 字 符 一 样 保留 字符 进行 编码 时 ， 或 者 当 你 需要 使 用 一 个 你 所 使 用 的 字符 集 里 面 不 支持 的 


你 可 以 在 XHP 中 以 文本 的 形式 使 用 HTML 字 符 引 用 语法 ， 在 解释 的 过 程 中 ， 它 将 会 被 转换 为 相应 的 字符 。XHP 支 持 HTML5 草 案 中 的 每 一 个 HTML 实 体 ， 当 然 还 有 数字 字符 引用 语法 。 


这 个 例子 将 会 输出 一 个 包含 三 个 新 的 <span> 标 记 。 第 一 个 使 用 实体 ， 第 二 个 使 用 十 进 制 计 数 法 ， 第 三 个 使 用 十 六 进 制 计 数 法 。 结 果 字 符 串 是 用 UTF8 编 码 的: 


echo <span>&hearts; &#9829; &#x2665;</span>; 


请 记 住 XHP 对 所 有 保留 的 HTML 字 符 都 进行 了 转 义 (这 里 包含 五 个 : &< >") ， 所 以 如 果 你 要 使 用 这 个 语法 来 创建 它们 中 的 某 一 个 ， 当 你 把 XHP 对 象 转化 为 一 个 字符 串 时 ， 它 将 会 转化 为 一 个 实体 。 这 
个 例子 将 会 输出 ? &amp; : 


echo <span>ghearts; &amp;</span>; 


在 XHP 里 面 ,没有 什么 办 法 可 以 直接 输出 一 个 像 &hearts; 一 样 的 字符 捉 。 


7.2.2 属性 


作为 对 子 元 素 的 补充 ，XHP 对 象 也 可 以 拥有 属性 。 属 性 是 一 个 可 以 在 对 象 中 保持 数据 的 键 / 值 对 。 这 和 HTML 很 类 似 ，HTML 标 记 可 以 使 用 属性 来 影响 它们 的 行为 。 每 个 XHP 类 定义 了 它 可 以 拥有 的 属 
性 ,每 个 属性 都 有 一 个 类 型 和 一 个 可 选 的 默认 值 。 属 性 可 能 还 是 必 选 的 。 这 就 是 说 ， 不 设置 会 引发 一 个 错误 。 


XHP 标 记 语 法 支持 属性 ， 并 且 它 们 看 起 来 和 HTML 属 性 非常 类 似 。 在 标记 名 称 后 面 ， 它 们 可 以 有 任意 数量 的 属性 ， 这 些 属性 用 空白 分 隔 。 每 个 属性 都 有 一 个 名 字 ， 跟 随 一 个 等 号 ， 然 后 是 一 个 值 。 在 等 
号 符号 周围 不 能 存在 空白 。 值 必须 是 一 个 双 引 号 字符 串 ， 或 者 是 一 个 花 括号 括 起 来 的 Hack 表 达 式 ( 见 7.2.3 节 ) 。 例 如 : 


echo <input type="button" name="submit" Value="Click Here" />; 


请 注意 ， 虽 然 属性 值 都 是 用 双 引 号 括 起 来 的 字符 串 ， 但 是 它们 不 能 像 在 其 他 地 方 一 样 ， 支 持 在 其 中 插入 变量 值 。 在 属性 值 里 面 的 $ 符 号 并 没有 任何 特殊 的 意义 。 如 果 你 需要 在 其 中 插入 变量 值 ， 那 么 请 使 
Hack 代 码 谋 入 作为 替代 ( 见 下 一 节 内 容 ) 。 


7.2.3 ”Hack 代 码 谋 入 


你 可 以 在 XHP 语 法 内 部 嵌入 Hack 表 达 式 来 使 用 这 些 表达 式 的 值 作为 属性 ,或 者 XHP 对 象 的 子 元 素 。 这 个 语法 是 非常 简单 的 : 使 用 花 括号 包 诸 Hack 表 达 式 。 这 里 有 一 个 例子 ,包含 了 你 可 以 使 用 它 的 两 
种 方式 : 一 种 是 作为 属性 ， 另 外 一 种 是 作为 子 元 素 。 


echo 
<a href={$user->getProfileURI () }> 
{$user->getName ()}'s Profile 
</a>; 


除了 允许 你 在 XHP 树 里 插入 动态 生产 的 数据 ， 它 还 允许 你 从 代码 片段 构建 一 个 XHP 树 ， 而 不 是 一 个 单独 的 大 块 : 


$linked profile pic = 
<a href={$user->getProfileURI () }> 
<img src={$user->getProfilePicURI()} /> 
</a>; 
echo 
<div> 


<div class="profile-pic">{$1linked profile pic}</div> 
{$user->getName () } 
</div>; 


这 就 相当 于 把 为 标记 <a> 的 代码 直接 放 到 了 <div> 标 记 内 。 


7.2.4 XHP 类 型 注解 


在 四 处 传递 XHP 对 象 的 时 候 ， 这 里 有 两 个 接口 可 以 用 做 类 型 注解 : XHPRoot 和 XHPChild。 


XHPRoot 可 以 是 XHP 类 实例 化 的 任何 对 象 。XHPChild 是 在 这 个 代码 中 作为 $xhpchild 的 合法 值 的 一 系列 事物 。 


echo <div>{$xhpchild}</div>; 


它 意味 着 XHP 对 象 ， 还 有 字符 串 、 整 型 、 双 精度 浮 点 型 以 及 任意 这 些 的 数组 。 它 并 不 包括 拥有 _tostring () 方法 的 非 XHP 对 象 。 XHPChild 在 其 中 是 特殊 的 ， 它 被 原始 类 型 “实现 ”。 所 以 举例 来 
说 ，123instanceofXHPChild 的 结果 是 true。 


这 里 有 个 范例 ， 用 于 你 可 能 使 用 XHPChild 的 情形 : 对 一 个 可 能 是 连接 或 者 非 连接 的 文本 进行 UI 元 素 渲染 的 时 候 。 


function render page link (Page $page, bool $is self): XHPChild { 
if ($is self) { 
return Spage->getTitle() 7 
} else { 
return <a href={$page->getURI () }>{$page->getTitle() }</a>; 
} 
} 


如 果 你 有 了 一 个 XHPChild， 并 且 出 于 参数 传递 的 目的 需要 把 它 包装 成 XHPRoot， 你 可 以 使 用 XHP 的 特殊 类 Xx: frag。 它 本 质 上 是 对 XHP 内 容 的 一 个 透明 包装 。 把 一 个 x: frag 作 为 子 对 象 添加 到 另外 一 个 
XHP 对 象 中 ， 和 单独 添加 x: flag 的 每 一 个 子 对 象 的 效果 是 一 样 的 。 当 你 需要 传递 一 组 多 个 XHP 对 象 ， 而 没有 什么 容器 来 承载 它们 的 时 候 ， 你 还 可 以 使 用 这 个 类 进行 包装 : 


function render name with icon(User $user): XHPRoot { 
return 汪 本 加 
<x:frag> 
<img src={$user->getIconURI ()} /> 
&nbsp; 
{$user->getName () } 
</x:frag>; 
} 


7.2.5 ”对 象 接口 


XHP 对 象 拥有 很 多 公有 方法 ， 它 们 可 以 用 于 观察 和 修改 它们 的 属性 和 子 对 象 。 这 可 以 给 你 更 多 的 灵活 性 : 当 你 创建 了 一 个 XHP 对 象 时 ， 你 不 需要 准备 好 它 的 所 有 子 对 象 及 属性 。 你 可 以 创建 一 个 对 象 ， 
然后 把 它 传递 给 其 他 函数 ， 这 样 其 他 函数 就 能 够 对 它 进 行 修改 了 。 或 者 从 函数 中 返回 一 个 对 象 ， 以 便 调 用 者 进行 定制 化 。 一 个 XHP 对 象 的 方法 有 : 


appendChild (mixed$child) : this 


在 这 个 对 象 的 子 对 象 数组 的 最 后 添加 一 个 $child。$child 也 可 以 是 个 数组 ， 数 组 中 的 每 个 成 员 都 会 按 顺 序 递 归 传 递 给 appendChild () 方法 。 


prependChild (mixed$child) : this 


在 这 个 对 象 的 子 对 象 数组 的 最 开始 位 置 添加 $child。$child 也 可 以 是 个 数组 ， 它 里 面包 含 的 对 象 都 会 按 顺序 递归 传递 给 prependChild () 方法 : 


replaceChildren (http://www.hzcourse.com/resource/readBook?path=/openresources/teach_ebook/uncompressed/16125/OEBPS/Text/...) : this 


这 个 函数 可 以 取 大 量 的 实 参 ， 把 这 些 实 参 放置 到 一 个 数组 中 ， 然 


getChildren (? st 


如 果 $se 


ting$selector=null) 


后 使 


: Vector<XHPChild> 


方法 将 会 返回 以 $selector 命 名 的 类 的 所 有 子 对 象 实例 : 


getFirstChild (? string$selector=null) : ? XHPChild 


如 果 $se 


null: 


ector 没 


getLastChild (? s 


如 果 没 有 传递 yselector， 它 将 返回 


getAttributes () 


有 被 传递 ， 它 将 返回 这 个 对 象 的 第 一 个 子 对 象 。 否 则 ， 它 将 会 返回 


tring$selector=null) 


: ? XHPChild 


: Map<string, mixed> 


返回 这 个 对 象 的 


属性 数组 。 返 回 的 Map 是 这 个 对 象 内 置 


这 个 对 象 的 最 后 一 个 子 对 象 。 否 则 ， 它 将 返回 


getAttribute (string$name) 


返回 以 hname 命 


: mixed 


属性 数组 的 一 个 拷贝 。 


名 的 属性 的 值 。 如 果 这 个 属性 没有 被 设置 ， 


回 


这 个 属性 不 


将 抛 出 XHPAttributeNotSupportedException 异 常 。 


如 果 你 正在 读 取 的 


setAttribute (stringy 


是 必需 时 ， 将 会 返 


name, mixed$val) 


属性 是 一 个 非 静态 可 知 的 


属性 ， 你 就 只 能 


: this 


设置 以 $name 命 名 的 属性 值 为 $val。 这 个 值 将 会 被 验证 是 否 和 属性 的 类 型 


选择 这 个 方法 了 。 否 则 ， 你 应 该 使 


你 可 以 放心 对 其 进行 修改 ， 而 不 必 担 心 


这 个 数组 对 相应 对 象 的 子 对 象 数组 进行 替换 : 


ector 没 有 传 入 的 话 ， 这 个 方法 会 简单 地 返回 这 个 对 象 的 所 有 子 对 象 。 如 果 $selector 以 % 开 头 ， 这 个 方法 将 会 返 


$this-> : name 语 法 ， 


作曲 
研 呆 /| 


响 到 这 个 对 象 本 身 。 


所 有 以 $selector 命 名 分 类 的 子 对 象 ( 详 见 7.3.3 节 的 相关 内 容 ) 。 否 则 ， 这 个 


匹配 $selector (细节 上 可 以 参见 getChildren () 方法 ) 的 第 一 个 子 对 象 ， 如 果 没有 这 样 的 child 存 在 ， 将 会 返回 


匹配 $selector (细节 上 请 参见 getChildren () 方法 ) 的 最 后 一 个 子 对 象 。 如 果 没 有 这 样 的 子 对 象 存在 ， 将 返回 null: 


null。 否 则 ， 将 会 抛 出 XHPAttributeRequiredException 异 常 。 如 果 $name 不 是 一 个 已 声明 


为 类 型 检查 器 明 


属性 的 名 字 ， 


这 点 ， 并 且 可 以 给 予 返回 值 正确 的 类 型 。 


匹配 ， 如 果 类 型 检查 失败 了 ， 这 个 方法 将 会 抽出 XHPlnvalidAttributeException 异 常 。 如 果 这 个 $gname 并 不 包含 一 个 已 经 声明 


setAttributes (KeyedTraversable< string, mixed>$attrs) 


使 


isAttributeSet (st 


再 次 说 明 ， 如 果 你 已 知 


$attrs 蔡 换 对 象 的 


ring$name) : bool 


返回 名 称 为 $gname 的 属性 是 否 被 设置 。 


categoryOf (strin, 


g$cat) : bool 


返回 这 个 类 是 否 


当 使 


已 经 存在 的 XHP 类 的 各 种 功能 时 ， 最 常 


getChildren () 和 g 


etAttribute () 。 


属性 名 称 ， 应 该 使 


属性 的 名 字 ， 它 将 会 抛 出 一 个 XHPAttributeNotSupportedException 异 常 。 


: this 


属于 名 称 为 $cat 的 分 类 。 


这 里 有 个 例子 , 使 


面向 对 象 的 接口 来 建立 一 个 HTML 列 表 : 


属性 数组 。setAttribute () 方法 的 错误 条 件 同样 适用 于 这 个 方法 。 


Sthis->: name=$value 语 法 ， 而 不 是 现在 的 这 个 方法 。 


的 功能 就 是 appendChild () 、prependChild () 和 setAttribute () 。 当 编写 一 个 自 定义 XHP 类 的 时 候 ( 见 7.3 节 ) ， 你 最 常 


的 就 是 


function build list (array<string> Snames) : XHPRoot { 


$list = <ul 


foreach 


J 


(Snames as Sname) { 


$list->appendChild (<1i>{$name}</1i>); 


i 


return $list; 


7.2.6 验证 


XHP 类 可 以 声明 类 型 ， 还 可 以 声明 能 够 拥有 的 子 对 象 的 数量 以 及 


属性 的 类 型 和 名 称 。 这 些 约束 在 不 同 的 时 间 得 到 了 验证 。 


“ 子 对 象 约束 在 泻 染 的 时 刻 进行 验证 。 这 就 是 说 ， 在 toStting () 函数 被 调用 的 时 候 验证 。 具 体 可 以 参见 7.6.2 节 以 查看 更 详细 内 容 。 


“ 属性 名 称 和 类 型 在 属性 被 设置 的 时 候 进 行 验证 。 或 者 在 一 个 XHP 标 记 中 ， 或 者 通过 setAttribute () 。 


“ 当 一 个 单独 的 @required 属 性 被 读 取 的 时 候 ，@required 属 性 的 出 现 会 被 验证 。 


默认 情况 下 ， 验 证 功能 是 开启 的 。 同 时 ， 也 可 以 关闭 它 。 在 开发 和 测试 中 ， 我 们 推荐 你 保持 这 个 功能 开启 ， 这 样 可 以 捕获 错误 。 如 果 在 生产 环境 下 ， 出 于 节省 CPU 有 周期 的 目的 ， 把 XHP 的 验证 功能 关闭 


是 个 快速 并 且 容 易 的 方式 。 所 有 你 需要 做 的 就 是 ， 在 开始 使 


:xhp: : $ENABLE VALIDATION = false; 


全 语法 高 亮 


通常 来 说 ， 在 流行 的 文本 编辑 器 中 ， 
导致 文本 被 错误 地 当 作 一 个 字符 串 字面 量 高 


XHP 之 前 确保 下 


面 这 条 语句 正常 运行 : 


解决 方案 就 是 ， 把 这 个 搬 号 放 到 一 个 嵌入 代码 片段 内 部 ， 置 于 用 双 引 号 括 起 来 的 字符 串 之 中 。 你 可 以 仅仅 包 衷 搬 号 本 身 ， 或 者 文本 的 更 大 部 分 ， 或 者 它们 之 间 的 其 他 任意 部 分 : 


自 带 的 PHP 语 法 高 亮 模 块 将 会 对 包含 XHP 的 文件 有 着 很 好 的 支持 。 主 要 的 麻烦 来 源 就 是 ， 在 包含 XHP 的 文本 之 中 使 用 搬 号 。 语 法 高 亮 会 把 这 些 作为 单 引 号 的 开始 ， 
亮 。 在 运行 时 ， 这 并 不 会 引起 一 个 语法 错误 ,但 是 在 一 个 文本 编辑 器 中 会 引起 阅读 上 的 困惑 。 


echo <p>So text editors don{"'"}t get confused</p>; 
echo <p>{f"This'11 work too"}</p>; 


任何 一 种 风格 都 没有 什么 技术 上 的 优势 。 相 比较 而 言 ， 没 有 使 用 撒 号 的 文本 也 不 需要 任何 形式 的 引号 。 这 种 情况 下 ， 在 文本 编辑 器 里 面 的 表现 形式 和 上 述 两 种 情况 中 的 第 一 种 风格 更 为 接近 。 


7.3 ”创建 你 自己 的 XHP 类 


XHP 的 强大 魔力 来 自 于 它 的 可 拓展 性 。 它 基于 每 个 标准 HTML 标 记 类 ， 但 是 你 可 以 定义 自己 的 类 对 泻 染 逻 辑 进行 封装 。 例 如 ， 你 可 以 定义 一 个 XHP 类 ， 这 个 类 用 于 代表 一 个 网 页 之 中 的 警告 框 ,或 者 
户 列表 中 的 一 行 ， 或 者 整个 导航 条 。 


XHP 类 名 总 是 由 一 个 冒号 (: ) 开始 ， 并 且 在 名 称 中 间 可 能 包含 着 冒号 ， 但 是 绝对 不 会 出 现 两 个 连续 的 冒号 。 冒 号 不 允许 出 现在 PHP 和 Hack 的 类 名 称 中 。 冒 号 的 使 用 是 XHP 引 进 的 新 变化 。XHP 的 类 名 
还 有 可 能 包含 连 字符 (-) ， 这 在 PHP 和 Hack 中 也 是 非法 的 。 


对 于 创建 一 个 自 定义 的 XHP 类 ， 你 所 需要 做 的 就 是 继承 : x: element， 并 且 实 现 被 保护 的 方法 render () ， 没 有 实 参 ， 并 且 返 回 一 个 XHP 对 象 。 这 里 有 个 迷你 范例 : 


Class :hello-world extends :x:element { 
protected function render(): XHPRoot { 
return <em>Hello World</em>; 
} 
} 


echo <hello-world />; // Prints <em>Hello World</em> 


值得 注意 的 一 点 是 ， 即 使 你 正在 定义 自己 的 XHP 类 ， 你 仍然 不 要 处 理 HTML 字 符 串 。 任 何 实现 都 必须 基于 其 他 自 定义 XHP 类 或 者 对 应 于 HTML 标 记 的 内 置 类 。 


render () 方法 的 返回 类 型 必须 是 XHPRoot， 所 以 它 必须 返回 一 个 人 HP 对 象 。 如 果 你 想 返 回 一 段 文本 字符 ， 那 么 请 使 用 x: frag 进 行 包 装 : 


class :hello-world extends :x:element { 
protected function render(): XHPRoot { 
return <x:frag>Hello world, plain as can be</x:frag>; 
} 
} 


7.3.1 属性 


你 定制 的 XHP 类 可 以 声明 自己 的 属性 。 在 类 定义 内 部 ， 放 置 一 个 XHP 的 保留 关键 词 attribute， 随 后 是 类 型 、 属 性 名 称 ， 还 有 一 个 可 选 的 默认 值 。 属 性 名 称 常规 上 都 是 小 写 的 ， 在 单词 之 间 没 有 任何 分 隔 
符 ， 就 是 为 了 模仿 HTML 所 使 用 的 风格 : 


class :ui:profile-link extends :x:element { 
attribute int profileid; 
attribute bool showpicture = false; 


i 


XHP 访 问 一 个 attribute 属 性 值 有 特殊 的 语法 。 它 看 起 来 很 像 常规 的 property 属 性 访问 语法 ， 使 用 attribute 属 性 名 称 作为 property 属 性 名 称 ， 但 是 attribute 属 性 名 称 是 用 冒号 开头 的 [1]: 


class :hello extends :x:element { 
attribute string target; 
Public function render(): XHPRoot { 
return <x:frag>Hello {$this->:target}!</x:frag>; 
} 
} 


如 果 一 个 属性 没有 被 设置 ， 将 返回 null， 如 果 设 置 了 默认 值 ， 将 返回 默认 值 。 


你 可 以 通过 在 声明 中 的 属性 名 称 后 添加 @required， 使 一 个 属性 变 为 必 选 的 。 如 果 你 试图 去 读 取 一 个 必 选 的 属性 ， 并 且 这 个 属性 没有 被 设置 的 话 ， 将 会 抛 出 一 个 XHPAttributeRequiredException 异 
常 。 值 得 注意 的 是 ， 如 果 这 个 异常 超出 了 render () 方法 的 范围 ，: x: element 将 会 捕获 这 个 异常 ， 然 后 把 它 转化 为 一 个 致命 错误 。 如 果 你 想 要 捕获 这 个 异常 ， 你 必须 在 render () 内 部 进行 捕获 ， 但 这 并 
不 是 推荐 的 办 法 。 相 反 ， 我 们 推荐 的 方法 是 : 如 果 它 真 的 是 必 选 的 ， 请 确保 这 个 属性 被 设置 ， 或 者 不 要 把 它 设置 为 必 选 。 


这 个 语法 要 求 你 结合 @required 和 默认 值 (在 默认 值 后 面 放置 @required) ， 但 是 这 样 语义 上 并 没有 什么 意义 。 如 果 你 没有 传递 这 个 属性 ， 当 你 试图 去 读 取 它 时 ,会 引发 一 个 
XHPAttributeRequiredException 异 常 ， 所 以 你 永远 不 会 看 到 这 个 默认 值 。 


你 可 以 给 属性 设置 的 类 型 是 Hack 类 型 注解 的 一 个 子 集 。 每 个 属性 都 必须 有 一 个 类 型 ， 并 且 属 性 类 型 在 运行 环境 中 进行 检查 ， 甚 至 在 不 使 用 Hack 类 型 检查 器 的 情况 下 也 是 。 


这 里 有 个 可 以 接受 的 属性 类 型 集合 ， 还 包括 它们 的 相关 含义 : 


“ bool、int、float、string、array 还 有 mixed。 这 些 都 和 它们 在 Hack 类 型 注解 ( 见 1.4 节 ) 中 的 含义 相同 。 黑 认 情 况 下 ， 这 里 没有 强制 转化 。 如 果 你 没有 传递 属性 所 期 待 的 正确 类 型 ， 将 会 抛 出 一 个 
XHPInvalidAttributeException 异 常 。 


“Hack 枚 举 名 称 ( 见 3.1 节 的 相关 内 容 ) 允许 使 用 。 它 们 在 运行 时 中 使 用 枚 举 的 isValid () 方法 进行 验证 。 如 果 检 查 失 败 了 ， 将 会 抛 出 XHPInvalidAttribute Exception 异 常 。 


“ 这 里 有 另外 一 个 枚 举 语法 ， 你 可 以 内 联 列 出 所 有 可 接受 的 值 。 它 看 起 来 是 这 样 的 : 


attribute enum {'get', 'post'} formmethod; 


这 里 对 列 出 的 可 能 存在 的 值 的 数量 并 没有 限制 。 所 有 的 值 必须 是 标量 (布尔 、 数 字 或 者 字符 串 字 面 量 ) ， 并 且 它 们 都 将 被 转化 为 字符 串 。 枚 举 属性 在 运行 时 中 会 被 检查 ， 使 用 = = = 检查 是 否 符合 可 接受 
值 的 列表 。 如 果 检 查 失败 ， 将 会 抛 出 一 个 XHPInvalidAttributeException 异 常 。 


对 于 和 Hack 枚 举 完全 没有 关系 的 ， 你 应 该 使 用 Hack 枚 举 进行 替换 。 因 为 Hack 的 枚 举 更 加 类 型 安全 ， 并 且 和 非 XHP 代 码 更 加 一 致 。 


“ 类 和 接口 名 称 被 允许 。 它 们 在 运行 时 中 将 使 用 instanceof 进 行 检 查 。 如 果 检 查 失 败 ， 将 会 抛 出 一 个 XHPInvalidAttributeException 异 常 。 


特别 需要 注 明 的 是 一 个 特殊 接口 Stringish。 它 和 XHPChild 一 样 特殊 : 它 被 一 个 原始 类 型 “实现 ” ， 换 句 话说 是 字符 串 。 它 还 被 任何 包含 _toString () 方法 的 类 ， 隐 式 地 实现 。 和 string 属 性 类 型 相 比 
较 ，string 类 型 只 接受 字符 串 ， 而 不 是 对 象 。 


泛 型 ( 见 第 2 章 ) 包括 数组 ， 当 用 作 属 性 类 型 的 时 候 ， 可 以 接受 类 型 实 参 。 还 可 以 应 用 类 型 擦 除 ， 所 以 虽然 Hack 类 型 检查 器 将 会 利用 类 型 实 参 ， 但 是 运行 环境 并 不 会 检查 它们 。 


在 属性 类 型 中 ， 类 型 别名 ( 见 3.2 节 ) 仍然 没有 解决 。nullable 类 型 作为 属性 类 型 ， 并 不 是 语义 有 效 的 ， 并 且 它 们 都 不 是 callable 类 型 。 


属性 继承 


一 个 类 应 该 支持 另外 一 些 类 的 所 有 属性 ， 这 是 非常 常见 的 。 最 常见 的 案例 就 是 ， 你 想 定制 的 XHP 类 来 支持 其 内 置 父 类 的 所 有 属性 。 例 如 ， 如 果 你 正在 设计 一 个 XHP 类 ， 用 于 演 染 页 面 中 一 个 有 阴影 的 盒 
子 模型 ， 你 可 能 希望 它 能 够 支持 HTML 标 记 <div> 的 所 有 属性 。 


这 个 语法 非常 简单 ， 你 需要 提供 一 个 关键 词 attribute， 随 后 紧 跟 另外 一 个 XHP 类 的 名 字 ， 名 字 中 包括 开头 的 冒号 : 


class :ui:drop-shadow-box extends :x:element { 
attribute :div; 


} 


但 是 请 一 定 要 注意 ， 这 里 仅仅 声明 了 属性 ; 对 于 : ui: drop-shadow-box 从 它 的 render () 方法 返回 的 <div> 对 象 ， 并 没有 自动 转移 : div 的 属性 到 这 个 <div> 对 象 上 。 为 了 澄清 这 一 点 ，: ui: drop- 
shadow-box 的 实现 可 能 看 起 来 是 这 样 的 : 


class :ui:drop-shadow-box extends :x:element { 
attribute :div; 
protected function render(): XHPRoot { 
return <div class="drop-shadow">{$this->getChildren() }</div> 
} 
} 


使 用 : ui: drop-shadow-box 的 代码 ， 可 能 接 下 来 要 这 样 做 : 


echo <ui:drop-shadow-box id="mainBox">{$stuff}</ui:drop-shadow-box>; 


在 HTML 结 果 输 出 中 ，< div> 将 不 会 设置 一 个 id 属性 。<ui: drop-shadow-box> 设 置 了 id 属性 ， 但 是 它 的 render () 方法 从 没有 读 取 这 个 属性 ， 所 以 这 个 属性 丢失 了 。 这 可 以 确定 不 是 你 想 要 的 。 


如 果 想 自动 传递 属性 ， 你 可 以 使 用 XHPHelpers 这 个 trait， 它 将 会 在 7.3.6 节 描述 。 


7.3.2 ”声明 子 对 象 


对 于 你 的 自 定义 XHP 类 所 允许 的 子 对 象 ， 你 可 以 并 且 应 该 声明 类 型 。 子 对 象 声 明 的 语法 和 常规 的 正则 表达 式 语法 很 类 似 。 为 了 使 这 些 例子 更 易于 理解 ， 将 会 展示 一 些 来 自 真实 的 HTML 标 记 的 声明 中 。 


如 果 这 里 没有 子 对 象 声 明 ， 当 前 类 人 允许 用 于 任何 数量 任何 类 型 的 子 对 象 。 同 一 个 类 用 于 多 重子 对 象 声 明 将 会 导致 一 个 语法 错误 。 


最 简单 的 子 对 象 声 明 是 empty， 这 意味 着 这 个 元 素 并 不 允许 拥有 任何 的 子 对 象 。 例 如 ， 像 : br 和 : hr 这 样 的 类 将 会 有 类 似 下 面 的 声明 : 


class :br extends :xhp:html-element { 

children empty; 

// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 


接 下 来 的 一 步 就 是 具体 到 名 字 的 XHP 类 (包括 开头 的 冒号 ) ， 然 后 把 他 们 放置 到 一 个 序列 之 中 ， 使 用 逗号 对 它们 进行 分 隔 。 


class :html extends :xhp:html-element { 

children (:head, :body); 

// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 


这 就 意味 着 <html> 标 记 要 求 按 顺 序 拥 有 一 个 <head> 子 对 象 和 一 个 <body> 子 对 象 ， 并 没有 其 他 子 对 象 。 


这 里 有 两 个 你 可 以 使 用 的 特殊 类 别 的 名 字 。 一 个 是 pcdata， 代 表 着 “解析 的 字符 数据 ”。 在 具体 实践 中 ， 它 意味 着 任何 可 以 被 转化 为 字符 串 的 Hack 值 。 另 一 个 是 any， 就 意味 着 无 论 是 一 个 XHP 对 象 ， 
还 是 解析 的 字符 数据 ， 任 何 东西 都 被 允许 。 注 意 这 些 名 字 并 没有 起 始 的 冒号 : 


class :option extends :xhp:html-element { 
children (pcdata)*; 
} 


接 下 来 就 是 使 用 重复 操作 符 * 和 + 。 在 另外 的 区 分 符号 后 面 放置 它们 ， 分 别 意味 着 “ 零 个 或 者 更 多 个 ”以 及 “一 个 或 者 更 多 个 ”。 


class :ul extends :xhp:html-element 1{ 
children (:1i)*; 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


class :dl extends :xhp:html-element { 
children (:dt+, :dd+)*; 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


正如 你 在 例子 中 所 看 到 的 : dl 一 样 ， 这 些 结构 应 该 被 包 应 在 括号 里 面 ， 并 且 还 有 其 他 的 结构 应 用 到 它们 上 面 。: dl 的 子 对 象 声 明代 表 的 意思 是 <dl> 的 子 对 象 必须 是 空 的 或 者 很 多 组 非 空 <dt> 跟 随 非 空 
<dd> 组 合 而 成 。 通 俗 地 说 ， 这 意味 着 它 的 子 对 象 必须 是 <dt> 或 者 <dd> ， 而 第 一 个 肯定 不 可 以 是 <dd> ， 最 后 一 个 也 不 能 是 <dt> 。 


这 里 还 有 另外 一 个 词尾 操作 符 ?”， 它 意味 着 “没有 或 者 一 个 该 对 象 ”。 


接 下 来 的 主要 内 容 是 选择 操作 符 |， 它 意味 着 “这 个 或 者 那个 ”: 


class :select extends :xhp:html-element { 
children (:option | :optgroup)*; 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


这 意思 是 说 ， 一 个 <select> 可 以 用 于 任何 数量 的 子 对 象 ， 但 这 些 子 对 象 必须 是 <option > 或 者 是 <optgroup>。 


分 类 名 称 。 它 们 被 % 进 行 前 缀 标识 : 


， 在 下 一 节 中 ， 我 们 将 会 对 其 细节 详细 学 习 。 在 一 个 子 对 象 声 明 中 ， 任 何 一 个 可 以 使 用 XHP 类 名 的 地 方 都 可 以 使 


最 后 一 个 需要 讨论 的 内 容 就 是 分 类 的 使 


class :strong extends :xhp:html-element { 


children (pcdata | %phrase)*; 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


} 


这 意味 着 <strong> 的 子 对 象 是 text， 或 者 是 分 类 %phrase 的 XHP 类 实例 。 


任何 可 能 的 结构 ， 并 且 显 示 了 一 些 更 深 的 刻 套 : 


关于 这 些 约束 条 件 如 何 更 丰富 地 描述 ， 这 里 有 个 范例 可 以 充分 进行 说 明 。 这 里 是 <table> 标 记 的 子 对 象 声 明 ， 它 使 用 了 几 和 


class :table extends :xhp:html-element { 
children ( 
:caption?, 
:colgroup*, 
:thead?, 
( 
(:tfoot, (:tbodyt+ | :tr*)) | 
(titbodyt | :tr*), :tfoot?) 
) 


); 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
L: 


7.3.3 分 类 


这 些 分 类 之 前 ， 它 们 并 不 需要 被 四 处 声 


非常 类 似 。 一 个 XHP 类 可 以 使 用 任何 数量 的 分 类 进行 标记 ， 这 些 分 类 可 以 用 于 从 子 对 象 声 明 中 进行 引用 。 在 使 


在 XHP 中 的 分 类 和 常规 面向 对 象 编程 中 的 接口 
明 。 这 个 语法 非常 简单 ， 在 category 关 键 词 后 面 列 出 分 类 ， 每 个 分 类 使 用 % 作 为 前 缀 ， 并 且 分 类 之 间 使 用 逗号 分 隔 : 


Class :strong extends :xhp:html-element { 
Category %flow, ®%Sphrase; 
children (pcdata | %phrase)*; 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


} 


定义 类 ， 分 类 并 不 应 该 使 用 。 你 可 能 想 知 道 ， 如 何 才能 避免 没有 添加 这 些 分 类 的 情况 下 ， 使 你 的 


上 


分 类 应 用 于 类 库 提供 的 HTML 标 记 实 现 ， 是 直接 从 HTML5 规 范 中 取得 的 。 并 且 一 般 来 说 ， 对 于 你 的 自 
定义 类 成 为 内 置 标记 的 子 对 象 。 例 如 ， 下 面 的 语句 就 是 合法 的 : 


class :hello-world extends :x:element { 
protected function render() { 
return <x:frag>Hello World</x:frag>; 
} 
} 


echo <strong><hello-world /></strong>; 


: hello-world 也 一 样 。 秘 诀 在 于 ， 这 里 有 两 个 独立 的 子 对 象 验证 阶段 。 


这 看 起 来 并 不 能 通过 验证 ， 因 为 : strong 要 求 它 的 子 对 象 或 者 是 pcdata， 或 者 拥有 分 类 %phrase， 而 且 这 两 个 条 件 都 不 为 真 ， 
这 将 在 7.6.2 节 中 进行 详细 描述 。 


7.3.4 上 下 文 


有 了 时候 你 可 能 会 发 现 ， 一 些 XHP 对 象 在 树 的 层级 非常 深 ， 需 要 通过 只 存在 于 最 顶层 的 一 条 信息 才能 够 被 访问 。 例 如 ， 一 个 网 站 上 的 某 个 按钮 可 能 需要 不 同 的 表现 样式 ， 表 现 样式 的 变化 依赖 于 它 的 使 
者 是 一 个 管理 员 ， 还 是 一 个 普通 用 户 。 目 前 为 止 ， 对 于 一 个 低级 别 的 对 象 ， 为 了 获取 上 述 类 似 信息 (如 果 这 里 没有 全 局 的 方式 去 获取 它 ) 。 唯 一 的 方式 就 是 ， 让 它 通过 顶部 的 每 一 层 逐 级 向 下 ， 把 对 应 信息 
作为 一 个 属性 进行 传递 。 这 种 方式 差强人意 : 不 仅 在 于 它 要 求 一 系列 乏味 重复 的 代码 来 定义 属性 并 且 进 行 传递 ， 还 在 于 它 打破 了 代码 封装 ， 人 迫使 高 级 别 的 对 象 为 了 它们 低级 子 对 象 的 需要 ， 而 直接 拥有 一 些 
属性 。 
上 下 文 (context) 引入 XHP 就 是 为 了 解决 这 种 问题 的 。 你 可 以 在 任何 


XHP 对 象 上 设置 上 下 文 信息 ， 然 后 当 这 个 对 象 被 泻 染 时 ， 它 将 会 把 它 的 上 下 文 向 下 传递 给 它 的 子 对 象 : 


$post list = <ui:post-list posts={$posts} />; 
$post_list->setContext ('user is admin', $user is admin); 


getContext () 方法 ， 进 而 获得 对 应 的 值 。 这 个 在 栈 深 处 的 类 ， 当 上 下 文 项 目 user_is admin 为 真 的 时 候 ， 才 会 对 一 个 帖子 中 的 删 


另 一 方面 ， 在 低级 别 的 对 象 中 ， 可 以 使 用 适当 的 名 称 作为 参数 来 调 
除 按钮 进行 泻 染 。 


class :ui:post extends :x:element { 
protected function render() { 
$delete button = null; 
if ($this->getContext('user is admin')) { 
$delete button = <ui:button style="delete">Delete Post</ui:button>; 


} 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


其 他 需要 注意 的 东西 : 
“上下文 仅 在 泻 染 期 间 在 树 上 传递 。 如 果 在 一 个 对 象 上 调用 setContext ('key'，'value') ， 然 后 马上 在 它 的 子 对 象 上 调用 getContext ('key') 的 话 ， 它 将 会 返回 null。 一 般 来 说 ， 你 应 该 仅仅 在 render () 方法 


内 部 调用 getContext () 方法 。 


“ 在 泻 染 期 间 ， 当 一 个 对 象 传递 上 下 文 给 它 的 子 对 象 时 ， 如 果 被 传递 的 上 下 文 对 象 和 子 对 象 有 着 一 致 的 键 ， 它 并 不 会 覆盖 子 对 象 的 上 下 文 。 例 如 : 


$inner = <inner />; 


$inner->setContext ('key', 'inner-value'); 
S$outer = <outer>{$inner}</outer>; 
$outer->setContext ('key', 'outer-value'); 


如 果 inner 对 象 调用 getContext ('key') 的 话 ， 它 将 会 返回 inner-value。 


7.3.5 ”异步 XHP 


XHP 集 成 了 Hack 的 异步 特性 ( 见 第 6 章 ) 。 当 定义 一 个 XHP 类 的 时 候 ， 你 可 以 在 它 的 泻 染 函 数 中 通过 两 步 来 使 用 异步 特性 。 


1. 在 类 的 内 部 使 用 XHPAsync 这 个 trait。 


2. 实 现 函 数 asyncRender () 而 不 是 render () 。asyncRender () 应 该 没有 形 参 ， 并 且 返 回 一 个 Awaitable<XHPRoot>。 例 如 : 


class :ui:external-api-status extends :x:element { 
use XHPAsync; 


protected async function asyncRender(): Awaitable<XHPRoot> { 
$status = await HH\Asio\cur] exec("https://example.com/api-status"); 
return <x:frag>Status: {$status}</x:frag>; 
} 
} 


XHP 的 基础 结构 将 会 检测 你 的 元 素 是 否 为 async， 并 且 使 用 asyncRender () 蔡 换 render () 。 


7.3.6 XHP 助 手 


XHP 提 供 了 一 个 叫做 XHPHelpers 的 trait， 它 实现 了 三 个 非常 有 用 的 行为 : 


“ 从 一 个 对 象 转移 属性 到 从 它 的 render () 方法 返回 的 另外 一 个 对 象 。 


. 给 每 个 对 象 唯一 的 id 值 。 


“ 对 类 属性 进行 管理 。 


属性 传递 


对 于 一 个 XHP 类 来 说 ， 从 另外 一 个 render() 方法 中 返回 自己 的 XHP 类 中 继承 属性 是 很 常见 的 。 例 如 ， 一 个 类 实现 了 一 个 有 阴影 的 盒子 ， 将 很 有 可 从 : div 继 承 属性 ， 因 为 它 将 把 这 个 盒子 当 作 <div> 进 


class :ui:drop-shadow-box extends :x:element { 
attribute :div; 
protected function render(): XHPRoot { 
return <div class="drop-shadow">{$this->getChildren () }</div> 
. 
} 


这 段 代码 的 问题 就 是 ， 你 在 一 个 ui: drop-shadow-box 实 例 中 设置 的 任何 属性 ， 将 会 简单 地 被 丢弃 。 因 为 从 它 的 render () 方法 返回 的 <div> 将 不 会 自动 获得 这 些 属性 : 


$box = <ui:drop-shadow-box title="the best box" />; 


// Prints <div class="drop-shadow"></div> 
echo Sbox->toString () 7 


为 了 获得 自动 传递 的 属性 ， 你 需要 在 希望 拥有 这 个 行为 的 类 中 ， 使 用 XHPHelpers 这 个 trait: 


class :ui:drop-shadow-box extends :x:element { 
attribute :div; 
use XHPHelpers; 


protected function render(): XHPRoot { 
return <div class="drop-shadow">{$this->getChildren () }</div>; 
} 
} 


现在 ， 在 ui: drop-shadow-box 被 泻 染 后 ，XHPHelpers 将 会 对 设置 在 ui: drop-shadow-box 上 的 所 有 属性 进行 遍历 。 对 于 每 个 属性 ， 如 果 从 render () 返回 的 对 象 声 明 了 这 个 属性 ，XHPHelpers 将 
把 它 传递 过 来 : 

$box = <ui:drop-shadow-box title="the best box" somename="somevalue" />; 

// Prints <div class="drop-shadow" title="the best box"></div> 

echo $box->tostring(); 

请 注意 属性 somename="somevalue" 并 没有 被 传递 。 这 是 因为 : ui: drop-shadow-box 这 个 盒子 并 没有 声明 它 ， 无 论 是 以 间接 (从 : div 中 继承 属性 ) 还 是 直接 的 方式 都 没有 对 这 个 属性 进行 声明 。 


当 传递 的 时 候 ， 设 置 在 : ui: drop-shadow-box 上 的 属性 将 会 对 设置 在 结果 <div> 上 的 同名 属性 进行 覆盖 。 例 如 : 


class :ui:drop-shadow-box extends :x:element { 
attribute :div; 
use XHPHelpers; 


protected function render(): XHPRoot { 
return 
<div class="drop-shadow" title="title on the div"> 
{$this->getChildren ()} 
</div>; 
} 
} 


$box = <ui:drop-shadow-box title="title on the box" />; 


// Prints <div class="drop-shadow" title="title on the box"></div> 
echo Sbox->toString () 7 


这 种 覆盖 行为 会 有 个 异常 : 类 属性 。 对 于 <div> 的 这 个 类 属性 值 不 是 简单 地 进行 值 覆盖 ，XHPHelpers 会 对 其 进行 附加 处 理 (确保 类 被 空格 分 开 ) 。 


$box = <ui:drop-shadow-box class="class-on-box" />; 


// Prints <div class="drop-shadow class-on-box"></div> 
echo Sbox->toString () 7 


唯一 ID 


在 网 页 编程 中 ， 给 DOM 节 点 设置 一 个 id 属性 是 非常 有 用 的 ， 这 样 的话 ，CSS 选 择 器 和 JavaScript 代 码 能 够 指向 他 们 。 然 而 ， 如 果 节 点 的 1D 不 唯一 ， 作 用 就 明显 小 多 了 。 


XHPHelpers 提 供 了 一 个 方法 ， 可 以 为 任何 元 素 设置 唯一 ID。 在 这 种 情况 下 ， 它 生成 随机 IDB]。 在 你 的 render () 函数 中 ， 只 需要 调用 getlD () : 


Class :hello-world extends :x:element { 
protected function render() { 
return <span id={$this->getID()}>Hello world</span>; 
} 
} 


管理 类 属性 


正如 我 们 现在 所 看 到 的 ，XHPHelpers 的 属性 传递 逻辑 会 对 类 属性 特殊 对 待 。 这 是 因为 DOM 节 点 的 类 属性 并 不 像 其 他 的 属性 : 从 语义 上 来 说 ， 它 的 值 是 一 组 值 ， 而 不 是 单一 值 。XHPHelpers 内 联 地 提 
供 了 两 个 方法 用 于 这 两 种 语义 : addClass () 和 conditionClass () 。 


addClass () 取 一 个 字符 串 作 为 实 参 ， 并 且 把 它 添加 到 对 象 的 类 属性 上 。 (当然 ， 对 象 的 类 必须 间接 或 者 直接 地 声明 类 属性 。) 它 确定 这 个 属性 值 的 存在 ， 并 且 附 加 的 新 值 会 使 用 空格 进行 分 隔 : 


class :ui:drop-shadow-box extends :x:element { 
attribute :div; 
protected function render(): XHPRoot { 
$div = <div />; 
$div->addClass ('drop-shadow'); 
$div->appendChild ($this->getChildren()); 
return S$div; 


conditionClass () 有 两 个 实 参 : 一 个 布尔 型 和 一 个 字符 串 型 。 如 果 布 尔 型 实 参 是 真 的 话 ， 它 将 直接 使 用 字符 串 实 参 调用 addClass () 。 


D attibute 和 property 两 者 中 文 都 是 属性 ， 具 体 的 区 别 很 微妙 ， 这 里 不 做 阐述 。 本 文中 的 属性 若非 特殊 注 明 ， 指 的 是 atttibute。 
D] 请 注意 你 将 会 看 到 一 些 类 ， 它 们 继承 自 :xshp:html-element， 而 不 是 :xelement。 详 细 信 息 可 以 参见 7.6.2 节 的 相关 内 容 ， 但 是 对 于 你 自己 的 XHP 类 来 说 ， 你 应 该 从 来 不 需要 这 样 做 。 
意味 着 ID 并 没有 保证 其 唯一 性 ， 但 是 在 同一 个 页 面 上 两 次 生成 同样 ID 的 概率 微乎其微 。 


[BB] 是 的 ， 这 


7.4 XHP 最 佳 实践 


HHVM 提 供 了 语法 ，Hack 类 库 提供 了 基础 架构 和 HTML 标 记 ， 但 在 这 些 基础 之 上 构建 一 个 好 的 UI 库 是 留 给 广大 读者 们 的 一 个 实践 项 目 了 。 这 里 有 一 些 开源 XHP 的 UI 框架 ， 随 着 时 间 的 积累 ， 这 里 将 会 有 
更 多 相关 的 开源 框架 涌现 ， 但 是 你 可 能 发 现 需要 自己 构建 全 部 或 者 其 中 的 一 部 分 。 


一 个 好 的 XHP 设 计 的 灵感 之 源 是 XHP-Bootstrap (https://github.com/hhvm/xhp-bootstrap) ， 这 是 一 个 Bootstrap (http://getbootstrap.com) 的 XHP 接 口 ，Bootstrap 是 一 个 非常 流行 的 通用 网 
站 UI 组 件 库 ， 组 件 库 里 面 有 按钮 、 下 拉 菜 单 、 导 航 栏 等 。 


XHP 对 于 大 多 数 的 PHP 和 Hack 开 发 人 员 来 说 都 是 一 个 不 熟悉 的 范式 。 因 为 他 是 相当 新 的 ， 关 于 如 何 设计 一 个 好 的 XHP 库 ， 这 里 没有 太 多 的 民间 智慧 可 供 参 考 。 本 节 代表 了 来 自 Facebook 的 相关 最 佳 实 
践 经 验 的 升华 总 结 ， 这 也 是 XHP 最 初 起 源 的 地 方 。Facebook 使 用 XHP 的 时 间 要 追 朔 到 2009 年 ， 在 2015 年 的 时 候 ， 它 的 前 端 页 面 代码 已 经 100% 使 用 XHP 来 生成 HTML 了 。 


7.4.1 ”没有 附加 的 公共 API 


XHP 类 代表 着 UI 组 件 。 一 个 XHP 类 的 使 用 者 应 该 能 够 使 用 标记 语法 来 创建 它 ， 并 且 可 以 把 它 泻 染 为 一 个 字符 捉 ， 并 没有 在 它 之 上 调用 任何 方法 。 (甚至 像 appendChild () 这 样 的 方法 ， 对 于 标记 语法 
来 说 ， 也 只 是 一 个 备 选 方案 。) 


在 XHP 类 中 ， 你 不 应 该 放置 任何 公共 方法 。 因 为 这 样 会 打破 它们 简单 代表 UI 组 件 库 的 约定 。 唯 一 你 需要 添加 到 XHP 类 的 公共 API 就 是 属性 及 子 对 象 声 明 。 


7.4.2 ”创作 ， 而 不 是 继承 


关于 XHP 类 设计 的 一 条 关键 原则 就 是 要 避免 使 用 继承 来 分 享 相关 功能 函数 。Facebook 原 本 非 XHP 的 UI 库 广泛 使 用 了 继承 。 当 我 们 迁移 到 了 XHP 后 ， 我 们 在 其 中 得 到 的 经 验 教训 就 是 ， 到 底 是 什么 驱使 
我 们 避免 继承 的 大 面积 使 用 。 


对 于 使 用 继承 的 “前 XHP” 来 说 ， 问 题 在 于 它 导致 了 下 面 两 件 事 中 的 一 件 : 难于 维护 的 代码 ， 非 最 优化 的 产 出 。 问 题 的 根源 在 于 ， 对 父 类 的 需求 允许 子 类 来 影响 他 们 的 行为 或 者 输出 。 这 里 有 产生 这 种 
影响 的 两 个 原因 : 


“ 指明 一 些 方法 是 “可 以 或 者 应 该 被 覆盖 ”。 对 于 避免 类 之 间 的 紧 耦 合 ， 这 种 方法 做 了 相当 好 的 工作 。 但 是 这 样 做 也 会 导致 灵活 性 的 缺失 ， 因 为 唯一 可 能 的 定制 项 都 是 父 类 的 设计 者 提前 想 好 的 。 


“ 不 允许 或 者 不 鼓励 对 受 保护 方法 的 覆盖 ， 相 反 ， 迫 使 子 类 对 从 父 方 法 返回 的 HTML 进行 修改 。 通 过 这 种 方法 ， 要 么 子 类 需要 知晓 父 类 实现 的 细节 ， 这 样 会 导致 过 分 的 紧 耦 合 ， 以 及 一 个 父 类 难于 修 
改 。 要 么 子 类 对 父 类 的 输出 ， 使 用 一 个 <div> 或 者 <span> 或 者 其 他 类 似 的 进行 简单 包装 ， 这 会 导致 非常 差 的 输出 体验 。 


通过 给 被 传递 的 对 象 提 供 一 个 面向 对 象 的 接口 ，XHP 一 定 程度 上 解决 了 后 一 个 问题 ， 但 继承 仍然 是 不 理想 的 。 最 主要 的 原因 就 是 ， 它 掩盖 了 控制 流程 : 阅读 代码 的 一 些 人 员 需 要 向 上 追踪 好 多 层 继承 来 
查找 相关 的 继承 方法 。 


使 用 XHP 的 UI 库 根本 不 该 需要 继承 。XHP 类 可 以 继承 属性 ( 见 7.3.1 节 的 相关 内 容 ) ， 并 且 由 于 “没有 附加 的 公共 API” 规 则 ， 所 有 你 所 需要 做 的 就 是 多 态 地 使 用 XHP 类 ， 多 态 是 传统 继承 的 主要 优势 。 


了 在 一 个 优秀 XHP 的 UI 库 里 有 一 个 用 于 继承 的 应 用 。 单 一 抽象 基 类 是 一 个 非常 好 的 主意 ， 它 是 所 有 其 他 类 直接 继承 的 基 类 。XHP-Bootstrap 就 做 了 这 样 的 事情 ， 它 定义 了 一 个 名 为 : bootstrap: base 的 基 


7.4.3 不 要 创建 控制 流标 记 


在 XHP 的 相关 介绍 之 后 ， 大 多 数 的 开发 人 员 将 会 有 强烈 的 冲动 在 XHP 中 创建 控制 流标 记 。 如 果 你 也 有 类 似 的 想法 ， 请 一 定 要 抵制 。XHP 并 非 设计 用 于 控制 流 ， 试 图 这 样 做 只 会 导致 烛 熔 而 又 低 效 的 结 


这 里 有 一 个 假想 的 <x: if> 标 记 的 使 用 范例 ， 这 个 标记 在 条 件 为 真 的 时 候 ， 会 对 它 的 第 一 个 子 对 象 进行 渲染 ， 和 否则 将 泻 染 第 二 个 子 对 象 : 


echo 
<x:if cond={is logged in()}> 
<ui:logged-in-nav-bar /> 
<ui:logged-out-nav-bar /> 
/> 


这 看 起 来 即 干净 又 优雅 ， 但 这 里 有 几 件 事 情 是 错误 的 。 首 先 ， 在 所 有 的 情况 下 ， 你 都 会 无 误 地 初始 化 一 个 无 用 的 对 象 。 请 记 住 ，XHP 是 用 于 创建 对 象 的 语法 糖 。 在 这 个 例子 中 ， 代 码 必须 对 : ui: 
logged-in-nav-bar 和 : ui: logged-out-nav-bar 进 行 初始 化 ， 直 到 最 终 的 泻 染 时 刻 都 要 保持 对 它们 的 内 存 分配 ， 然 后 把 其 中 一 个 扔 掉 而 不 进行 最 终 泻 染 。 这 是 低 效 的 ， 并 且 打 破 了 XHP 树 和 最 终 的 HTML 
树 之 间 的 一 致 性 。 


第 二 个 问题 就 是 它 不 成 规模 。 前 一 个 例子 是 干净 而 优雅 的 ， 但 是 一 旦 <x: if> 中 的 两 个 子 对 象 变 得 复杂 ， 可 读 性 将 被 迅速 破坏 : 


echo 
<x:if cond={is logged in()}> 
<x:if cond={User is admin()}> 
<div> 
<ui:admin-link /> 
<ui:logged-in-nav-bar /> 
</div> 
<ui:logged-in-nav-bar /> 
</x:if> 
<ui:logged-out-nav-bar /> 
/if>} 


所 以 ， 一 些 条 件 结构 是 很 尴 炊 的 。 但 是 如 果 换 成 循环 呢 ? 这 里 有 一 个 假想 的 <x: foreach> 类 ， 它 模仿 了 Hack 中 的 一 个 foreach 循 环 : 


echo 
<ul> 
<x:foreach seq={$items} func={function ($item) { 
return <li>{$item}</1i>; 
1} /> 
</ul>; 


这 看 起 来 更 合情合理 。 没 有 无 用 的 XHP 对 象 被 初始 化 ， 并 且 它 的 精细 程度 也 很 好 : 传递 给 <x: foreach> 对 象 的 闭 包 ， 可 以 在 不 影响 清晰 度 的 前 提 下 ， 增 加 功能 复杂 度 。 


但 是 请 记 住 ，XHP 仅 仅 是 对 象 创建 的 语法 糖 。 如 果 你 对 这 种 情况 下 发 生 的 一 切 仔细 观察 ， 会 清晰 地 发 现 <x: foreach> 类 非常 糟糕 。 这 里 是 上 面 代码 的 一 个 “ 非 糖 ” 版 本 : 


echo new xhp ul (array( 
new xhp x foreach(array( 
'seq' => $items, 
"func' => function ($item) { 
return new xhp 1i (array ($item) ); 


这 个 方案 创建 了 一 个 用 于 代表 循环 的 对 象 ， 这 是 很 思春 的 行为 : 请 不 要 创建 一 个 对 象 来 代表 一 个 循环 ， 直 接 写 出 循环 就 好 ! 当 披 上 XHP 语 法 的 外 衣 后 ， 这 个 对 象 表面 上 效仿 了 一 个 常规 Hack 的 foreach 
循环 ， 但 是 事实 上 非常 不 同 。 


我 们 推荐 的 方案 是 ， 在 一 个 常规 Hack 循 环 中 使 用 appendChild () 。 这 个 结果 是 很 容易 看 懂 的 : 


人 IT = <ul > 
foreach ($items as Sitem) { 
$ul->appendChild (<1i>{item}</1i>); 


} 
echo S$ul; 


7.4.4 ”区 分 来 自 子 对 象 的 属性 


当 你 设计 一 个 XHP 类 的 时 候 ， 你 将 经 常 必须 选择 什么 应 该 是 个 属性 和 什么 应 该 是 个 子 对 象 。 来 自 XHP 的 哲学 角度 上 ， 这 个 选择 的 指导 原则 来 自 于 它 是 否 代表 一 个 最 终 的 DOM 树 : 如 果 一 个 值 和 在 DOM 
树 中 的 节点 一 致 ， 它 应 该 是 个 子 对 象 ; 否则， 它 应 该 是 个 属性 。 


这 里 有 一 些 例子 ， 灵 感 来 源 是 XHP-Bootstrap 以 及 Facebook 的 内 部 UI 库 : 
“ 代表 一 个 按钮 的 类 可 能 需要 用 于 表示 视觉 风格 (“cancel”，“default” 等 ) 以 及 不 可 用 性 的 相关 属性 ， 并 且 会 把 它 的 说 明文 字 当 作 一 个 子 对 象 对 待 。 


: 代表 一 个 对 话 框 的 类 ， 可 能 需要 代表 视觉 风格 (“note”，“warning” 等 ) 的 属性 ， 并 且 它 会 把 header、body 以 及 footer 作 为 子 对 象 。 


这 方面 最 主要 的 推论 是 : 没有 什么 属性 是 用 XHP 类 作为 其 类 型 。 


7.4.5 风格 指南 


XHP 应 该 有 它 自己 的 一 套 风格 指南 : 


“ XHP 类 名 称 的 独立 词语 之 间 应 该 使 用 连 字符 。 类 名 称 应 该 是 全 部 小 写 的 。 


“ 在 XHP 类 名 称 中 使 用 冒号 来 组 成 命名 空间 。 例 如 在 同一 个 代码 库 中 ， 如 果 你 的 网 站 同时 具有 桌面 版 和 移动 版 ， 在 每 个 版 本 中 你 可 能 需要 有 一 个 类 用 于 导航 栏 。 请 像 这 样 命名 ，: desktop: nav-bar 和 : 
mobile: nav-bar。 然 而 ， 这 仅仅 是 个 惯例 ， 这 里 并 没有 真正 的 命名 空间 语义 。 例 如 ， 从 : mobile: nav-batr 内 部 ， 当 引用 前 组 是 : mobile 的 其 他 XHP 类 时 ， 你 仍然 必须 包含 其 前 缓 : mobile， 并 不 能 省 略 掉 。 


“ 每 一 个 类 都 必须 使 用 一 次 atttibute 关 键 词 ， 并 且 所 有 的 属性 定义 都 应 该 跟随 在 后 面 ， 使 用 过 号 分 隔 : 


class :photo-frame extends :x:element { 
attribute 
:div, 
string caption, 
string imgsrc Q@required, 
enum {'compact', "ful1'} style; 


} 


7.5 “迁移 到 XHP 


在 一 个 理想 的 世界 中 ， 我 们 并 不 必 处 理 丑 陋 的 历史 遗留 代码 。 我 们 将 会 非常 自由 地 在 美丽 整洁 的 抽象 层 上 创建 抽象 代码 ， 总 是 选择 手头 问题 的 最 佳 设 计 方案 ， 我 们 的 代码 和 当前 的 任务 都 是 和 谐 匹 配 
的 。 


但 是 我 们 生活 在 真实 的 世界 中 ， 在 这 里 百 万 行 的 遗留 代码 仍然 在 服役 ， 并 且 在 短 时 间 内 不 可 能 会 下 线 。 新 的 工具 和 抽象 概念 需要 能 够 和 老 的 代码 协同 工作 。 这 对 XHP 来 说 是 相当 容易 的 事情 ， 但 是 这 里 
仍然 有 一 些 事情 需要 特别 注意 。 


7.5.1 自 下 而 上 的 转化 


把 遗留 UI 代 码 转化 为 XHP 最 平滑 的 办 法 ， 就 是 自 下 而 上 地 使 用 代码 进行 工作 。 这 就 是 说 ， 从 那些 不 依赖 于 其 他 代码 、 最 基础 的 低级 组 件 开始 ， 把 它们 转化 为 XHP。 例 如 ， 思 考 下 面 的 例子 : 


function render profile link($user) { 
Suri = htmlspecialchars ($user->getProfileURI ()); 
Sname = htmlspecialchars ($user->getName ()); 
return "<a href=\"$uri\">$name's Profile</a>"; 


} 


把 这 段 代 码 转化 为 XHP 破 坏 性 最 小 的 方式 就 是 创建 HTML 结 构 ， 然 后 把 它 转化 为 字符 串 ， 并 且 全 部 在 函数 内 部 完成 : 


function render profile link($user) { 
ink 


<a href={$user->getProfileURI () }> 
{Suser->getName () } 's Profile 
</a>; 
return $1link->toString(); 
} 


这 个 改变 非常 容易 ， 因 为 都 是 在 它 内 部 完成 的 ， 这 并 不 需要 你 修改 函数 的 调用 者 ， 但 是 这 对 代码 转化 的 贡献 微乎其微 。 问 题 在 于 ， 数 据 仍然 是 以 HTML 字 符 串 的 形式 跨越 抽象 边界 ， 而 不 是 以 XHP 对 象 
的 形式 ， 这 步 代码 转化 对 这 个 事实 并 没有 做 出 任何 改变 。 调 用 者 仍然 必须 考虑 转 义 ， 并 且 不 能 理智 地 修改 从 render_profile link () 返回 的 内 容 。 对 于 使 用 render_profile link () 的 组 件 这 一 级 别 进行 转 
化 ， 使 用 XHP 仍 然 是 件 很 尴 炊 的 事情 ， 因 为 你 需要 弥补 HTML 字 符 串 和 原始 字符 串 之 问 的 差别 。 


最 好 就 是 把 render_profile link () 转化 为 一 个 XHP 类 : 


class :ui:profile-link extends :x:element { 
attribute User user Q@required; 
protected function render(): XHPRoot { 
$user = $this->:user; 
return 
<a href={$user->getProfileURI () }> 
{$user->getName ()}'s Profile 
</a>; 
} 
} 


为 方便 起 见 ， 你 可 以 对 render_profile_link () 的 一 个 版 本 保持 包装 ， 这 个 版 本 仅仅 是 对 应 XHP 类 的 一 个 委托 : 


function render profile link($user): string { 
return (<ui:profile-link user={$user} />)->tostring(); 


} 


但 是 一 定 要 知道 ， 这 个 函数 只 是 个 拐杖 。 我 们 真实 的 目标 是 转化 每 一 个 对 render_profile_link () 的 调用 ， 使 用 <ui: profile-link> 来 进行 替换 ， 然 后 删除 这 个 拐杖 函数 render_profile link () 。 


7.5.2 ”避免 XHP 转 义 


正如 我 们 在 7.1.2 节 看 到 的 ， 你 嵌入 到 XHP 结 构 体 的 任何 字符 串 ， 作 为 一 个 XHP 对 象 被 转化 为 一 个 字符 串 的 时 候 ， 将 会 对 其 中 的 HTML 保 留 字 符 进行 转 义 。 这 是 非常 棒 的 事情 ,会 使 XHP 默 认 安全 ， 并 可 
于 防范 XSS 漏 洞 攻击 。 


然而 ， 有 时 候 这 个 行为 并 不 是 你 想 要 的 。 例 如 ， 你 可 能 会 使 用 来 自 某 个 类 库 的 函数 ， 这 个 函数 将 会 返回 一 段 HTML 字 符 串 。 这 个 类 库 用 于 演 染 类 似 Markdown 的 标记 格式 。 所 以 它 必 须 原样 输出 ， 而 不 


在 XHP 的 基础 架构 中 ， 有 一 个 故意 留 下 的 后 门 。 它 允许 类 的 创建 (常规 的 类 ， 并 非 XHP 类 ) 可 以 免 于 转 义 和 验证 。 这 主要 来 自 于 如 下 两 个 接口 : 


XHPUnsafeRenderable 


这 个 接口 声明 了 一 个 方法 toHTMLString () 。 它 并 没有 任何 实 参 ， 且 返回 一 个 字符 串 。 对 于 实现 了 这 个 接口 的 对 象 ， 你 可 以 把 它 放置 到 一 个 XHP 对 象 树 上 ，XHP 的 基础 架构 泻 染 引擎 将 会 把 调 
toHTMLString () 的 结果 直接 放 进 返回 的 HTML 字 符 串 之 中 ， 并 不 会 进行 转 义 。 


XHPAlwaysValidChild 


这 是 一 个 实现 了 特殊 功能 的 接口 类 ， 它 对 于 任何 XHP 对 象 都 是 一 个 合法 的 子 对 象 ， 除 非 对 应 的 XHP 类 有 个 子 对 象 empty 的 声明 (具体 参见 7.3.2 节 的 相关 内 容 ) 。 这 个 接口 自身 没有 声明 任何 方法 。 


XHP 类 库 并 不 附带 任何 实现 上 述 接口 的 类 。 因 为 理想 情况 下 ， 它 们 应 该 是 不 需要 的 。 并 且 使 用 它们 会 有 安全 上 的 隐患 ， 对 于 这 些 不 安全 的 事情 ， 我 们 希望 创建 一 个 障碍 来 阻止 它们 。 这 样 虽然 它们 可 以 
实现 ， 但 是 你 能 在 做 它们 之 前 知道 可 能 存在 的 风 


尺 


在 这 样 严 后 的 警告 之 下 ， 这 里 有 一 个 类 的 例子 ， 它 从 一 个 外 部 语法 高 亮 的 库 中 获得 HTML 字 符 串 ， 然 后 把 它 添加 到 XHP 树 中 : 


class SyntaxHighlight implements XHPUnsafeRenderable { 
private string $content; 


public function _ construct (string $source) { 
$this->content = external highlighting function ($source); 


} 


public function toHTMLString () : 
return $this->content; 
水 


string { 


这 里 有 一 个 如 何 使 


它 的 例子 : 


7:6:1 


$code = <div>{new SyntaxHighlight ($source) }</div>; 


7.6 XHP 内 部 原理 


本 节 的 内 容 是 选读 内 容 ， 对 于 希望 了 解 XHP 背 后 运行 原理 的 读者 ， 可 以 详细 阅读 这 里 的 内 容 。 你 并 不 需要 理解 任何 本 节 的 内 容 来 高 效 地 使 


XHP。 


XHP 有 2 个 组 件 : 解析 器 级 别 的 转换 组 件 ， 它 负责 把 标记 语法 转化 为 一 个 new 表 达 式 。 而 Hack 类 库 包含 核心 对 象 到 字符 串 的 基础 架构 ， 以 及 HTML 标 记 的 实现 。 


解析 器 转换 


当 XHP 语 法 被 解析 的 时 候 ， 解 析 器 把 它 转 化 成 了 常规 的 Hack 语 法 : 


" XHP 类 名 称 (和 


1. 开 始 的 冒号 使 


xhp 进行 替换 。 


2. 除 了 开始 的 冒号 之 外 的 其 他 冒号 被 替换 成 ( 双 下 划 线 ) 。 


3. 连 字符 被 替换 成 了 ( 单 下 划 线 ) 。 


例如 ， 类 名 称 : ui: nav-bar 将 内 部 转化 为 xhp_ui_nav_bar。 这 个 转化 被 应 


错误 信息 将 会 使 


些 以 冒号 开始 的 ) 被 转化 为 如 下 的 合法 Hack 类 名 称 : 


这 些 转换 过 的 名 字 ， 这 就 是 我 仔细 解释 这 部 分 内 容 的 原因 。 


到 XHP 类 定义 上 ， 还 有 这 些 类 名 称 被 使 有 


的 地 方 。 


“ 子 对 象 、 分 类 和 属性 定义 将 被 转化 为 受 保护 方法 的 定义 。 每 个 方法 什么 都 没 做 ， 只 是 返回 包含 这 个 声明 编码 的 数组 。 这 个 数组 的 格式 是 一 个 实现 细节 ， 和 XHP 的 用 户 无 关 。 


“ XHP 标 记 语法 被 替换 为 一 个 新 的 表达 式 。 两 个 实 参 会 传递 给 这 个 XHP 类 的 结构 体 : 一 个 属性 数组 (名 称 对 应 值 ) ， 以 及 一 个 子 对 象 数组 。 这 里 有 个 例子 : 


echo 
<a href="/signup.php"> 
Subscribe to <span class="brand">The Dispatch</span> 
</a>; 


// Is transformed into: 
echo new xhp al( 
array ('href' => '/signup.php'), 
array( 
'Subscribe to ', 
new xhp span( 
array('class' => 'brand'), 
array ('The Dispatch') 


TT 


有 实 上 ， 你 可 以 手工 书写 第 二 种 风格 的 代码 ， 并 且 它 能 正常 工作 。 


7.6.2 ”Hack 类 库 


Hack 类 库 定 义 了 一 些 抽象 类 ， 由 它们 组 成 了 XHP 的 核心 对 象 到 字符 串 转化 的 基础 架构 。 我 们 将 会 在 苞 


7-1 中 对 类 的 


层次 结构 进行 说 明 : 


:x:composable-element 


自 定义 类 代码 
放 这 里 


HTML 标 记 类 
放 这 里 


下 面 是 在 这 个 层级 中 展示 的 核心 类 的 细节 : 


: xhp 


图 7-1: XHP 的 核心 类 结构 


属性 ， 也 没有 任何 非 静 态 方法 。 


它 定义 了 


: X: Com 


它 扩展 了 : 


于 表现 XHP 对 象 的 接 [ 


osable-element 


xhp， 并 且 还 是 个 抽象 


组 、attribute, 


属性 以 及 上 下 文 。 


。 接 


的 类 ， 


中 声明 了 一 些 抽象 方法 ， 将 应 


但 是 已 经 有 了 很 多 有 形 的 功能 : 


它 提供 了 子 对 象 和 


: x: primitive 和 : x: element 


于 所 有 的 XHP 对 象 : 取得 和 设置 子 对 象 以 及 attribute 属 性 。 接 口 本 身 没 有 任何 property, 


属性 管理 方法 的 实现 ， 还 有 分 类 子 对 象 的 验证 ， 以 及 属性 的 约束 。 它 声明 了 一 些 property 属 性 : 子 对 象 数 


它们 都 继承 自 : x: composable-element， 同 时 都 是 抽象 的 。 它 们 的 关键 不 同 在 于 : x: primitive 期 待 它 的 子 类 要 实现 一 个 叫做 stringify () 的 方法 。 这 个 方法 将 会 返回 一 个 字符 串 。 而 : x: element 
区 别 非常 关键 : 它 开启 了 两 个 不 同 的 验证 阶段 ， 它 允许 内 置 类 和 自 定义 类 无 颖 地 进行 混合 。 而 对 于 自 


期 待 它 的 子 类 来 实现 一 个 叫做 render () 或 者 asyncRender () 的 方法 ， 


定义 类 ， 仍 然 执行 有 意义 的 验证 工作 。 


这 个 关键 的 操作 称 之 为 “冲洗 (flushing) ” : 通过 反复 对 它 调 
所 有 子 对 象 都 是 : x: primitive 对 象 为 止 。 这 


所 以 这 个 过 程 最 终 肯 定 会 结束 。 


“冲洗 ”一 个 : x: element 树 ， 通 过 对 每 个 元 素 的 asyncRender () 递归 调用 和 | 等待， 创建 了 一 个 异步 依赖 树 ( 见 6.3 节 的 相关 内 容 ) 。 通 过 这 种 方法 ， 多 个 元 素 可 以 并 行 地 泻 染 。 对 树 上 : 


元 素 也 可 以 并 行 泻 染 。 


对 于 单一 XHP 对 象 (也 就 是 对 应 树 的 根 ) ， 你 可 以 通过 调 


tostring () 方法 (或 者 调 


于 返回 一 个 XHP 对 象 。 这 个 


并 等 待 asyncToString () 方法 ) ， 启 动 转化 XHP 树 到 字符 串 的 过 程 。 


* : XxX: element 的 toStting () 会 对 元 素 的 子 对 象 进行 验证 (验证 的 第 一 阶段 ) ， 对 每 个 元 素 进行 “冲洗 ”， 然 后 调用 基于 结果 所 得 的 : x: primitive 的 toString () 方法 。 


: x: primitive 的 toString () 会 对 所 有 元 素 的 子 对 象 进行 “冲洗 ” 


sttingify () 方法 ， 最 后 把 所 有 的 结果 字符 串 连 接 起 来 。 


最 后 的 细节 是 类 库 里 面 代表 HTML 标 记 的 类 的 位 
: xhp: html-singleton， 它 并 不 允许 拥有 子 对 象 ) ， 但 它们 都 应 当 被 认为 是 XHP 内 部 的 类 ， 并 不 是 为 了 在 类 库 外 面 使 


HTML 标 记 的 特殊 原型 (例如 ， 


。 它 们 全 部 继承 


(使 用 HH\Asio\m () 同时 等 待 它们 都 “冲洗 ” 


完毕 ) 


: xhp: html-element, 而 : xhp: html-element 继 承 自 : x: primitive。 这 里 有 一 些 : xhp: html-element 的 子 类 ， 上 


而 存在 的 。 
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render () 或 者 asyncRender () ， 把 : x: element 转 换 为 : x: primitive， 然 后 递归 地 对 它 的 子 对 象 进行 “冲洗 ”， 直 到 它 和 它 的 
个 泻 染 方法 可 以 返回 任何 XHP 对 象 ， 并 且 继 承 的 : x: element 自 定义 类 可 能 由 很 多 层 所 组 成 。 但 在 栈 的 底部 必须 是 来 自 XHP 类 库 中 继承 自 : x: primitive 的 类 ， 


他 级 别 的 


， 验 证 被 冲洗 的 子 对 象 (验证 的 第 二 阶段 ) ， 然 后 调用 每 个 子 对 象 上 的 


于 代表 


在 语言 层次 上 ，HHVM 意 味 着 标准 PHP 解 释 器 的 直接 替代 品 。 


仅 因 为 它 是 just-in-time (JIT) 编译 器 。 


在 本 章 中 ， 你 将 会 学 到 


HHVM 上 


于 网 站 流 


时 的 基础 设置 。 当 然 ， 许 多 细节 还 取决 


晰 的 理解 ， 然 后 你 能 够 弄 明 


如 何在 你 的 设置 过 程 中 整合 它 。 


当 从 命 


本 章 并 不 包含 Hack 类 型 检查 器 的 设置 问题 ， 它 只 在 开发 的 时 候 才 会 


令 行 运行 脚本 的 时 候 ， 我 们 通常 坚信 这 一 点 。 然 而 ， 当 上 


于 Web 应 


你 的 特定 应 有 


到 。 如 果 你 想 了 解 相关 信息 ， 请 查看 第 1 章 的 内 容 。 


服务 ， 配 置 和 部 署 HHVM 的 方式 是 不 同 的 。 这 其 中 的 原因 ， 不 


程序 和 基础 架构 情况 ， 所 以 本 章 不 可 能 是 个 完整 的 指南 。 本 章 的 目标 就 在 于 给 你 一 个 对 HHVM 足 够 清 


8.1 指定 配置 选项 


HHVM 有 着 大 量 的 配置 选项 ， 多 到 在 本 书 中 不 可 能 面面俱到 。 它 们 中 的 很 多 部 分 并 不 是 面向 终端 用 户 ， 而 是 面向 HHVM 自 身 的 相关 人 员 。 在 本 节 中 ， 我 们 将 会 对 如 何 设置 配置 选项 以 及 什么 是 最 重要 的 


选项 进行 讲述 。 


HHVM 的 配置 文件 是 INI 格 式 的 ， 这 和 标准 的 PHP 解 释 器 所 使 用 的 配置 具有 相同 的 格式 。 你 可 以 使 用 一 个 -c 标 志 位 来 指明 一 个 配置 文件 : 


$ hhvm -c config.ini file.php 


1NI 格 式 是 非常 直接 了 当 的 。 每 个 选项 都 包含 一 个 键 / 值 对 。 每 对 在 INI 文 件 中 都 是 一 个 单独 的 行 ， 键 和 值 直接 使 用 等 号 分 隔 (空白 字符 存在 与 否 并 不 重要 ) : 


hhvm.dump bytecode = 1 
hhvm.1log.file = /tmp/hhvm.1log 


一 些 配 置 选 项 是 关联 数组 。hhvm.server_variables 就 是 一 个 例子 。 它 设置 了 PHP 和 Hack 的 $_SERVER 变 量 的 内 容 。 你 可 以 像 这 样 使 用 INI 格 式 对 这 些 选项 进行 配置 : 


hhvm. server_ variables [ENVIRONMENT] = prod 
hhvm. server variables[A NUMBER] = 314 


在 此 配置 下 的 PHP 和 Hack 程 序 ，$_SERVER 将 会 在 这 些 键 下 拥有 这 些 值 : 


var dump($_ SERVER['ENVIRONMENT']); // Prints: string(4) "prod" 
Var_dump ($_ SERVER['A NUMBER']); // Prints: int (314) 


你 还 可 以 在 shell 命 令 行 中 直接 配置 这 些 选项 。 使 用 -d 标 志 位 ， 然 后 跟随 一 个 INI 格 式 的 键 / 值 对 。 请 确保 其 中 没有 空白 字符 ， 也 没有 使 用 引号 的 情况 。 否 则 这 个 shell 将 会 把 它 分 隔 成 多 个 实 参 ， 最 终 导致 
HHVM 曲 解 这 些 项 目 : 


$ hhvm -d hhvm.dump_bytecode=1 file.php 


你 还 可 以 在 同一 个 命令 里 面 对 多 个 配置 文件 和 直接 的 选项 进行 合并 : 


$ hhvm -c configl.ini -d hhvm.dump bytecode=l1 -c config2.ini file.php 


通过 这 种 方式 ， 同 一 个 选项 可 以 被 多 次 配置 。HHVM 将 会 从 左 到 右 读 取 命令 行 ， 然 后 从 上 到 下 读 取 配置 文件 。 某 一 个 选项 的 值 最 终 取决 于 它 最 后 一 次 被 读 取 的 值 。 例 如 ， 在 前 一 个 命令 行 中 ，-d 
hhvm.dump_bytecode=1 将 会 对 config1.ini 文 件 中 对 hhvm.dump_byte code 的 任何 设置 进行 覆盖 。 如 果 这 个 选项 在 config2.ini 中 也 进行 了 设置 ， 那 么 将 再 次 发 生 覆 盖 。 


一 般 来 说 ， 对 于 生产 中 的 使 用 ， 最 好 在 单一 文件 中 对 所 有 的 选项 都 进行 配置 ， 简 单 地 通过 避免 依赖 的 顺序 来 确保 配置 选项 的 一 致 性 。 


中 | 
man 


要 的 选项 


接 下 来 是 HHVM 中 最 重要 的 一 些 配置 选项 : 


hhvm.enable_obj_destruct_call (布尔 型 ， 默认 值 是 off) 


这 个 选项 是 off 的 话 (默认 值 是 off) ， 一 个 请 求 结束 时 ， 对 象 仍然 保持 活跃 ，HHVM 将 不 会 运行 该 对 象 的 _destruct () 方法 。 而 其 他 时 候 ， 它 还 会 像 通常 那样 运行 _destruct () 方法 。 如 果 你 的 程序 
能 够 对 此 进行 容忍 ， 那 么 就 会 获得 显著 的 性 能 提升 。HHVM 不 必 在 请 求 结束 时 对 仍然 存活 的 每 个 数组 和 对 象 进行 遍历 ， 而 是 可 以 一 次 性 释放 所 有 请 求 的 内 存 。 如 果 这 个 选项 是 on 的 话 ，HHVM 将 会 在 任何 情 
况 下 ， 像 平常 一 样 运行 所 有 的 _destruct () 方法 。 


hhvm.hack.langlook_for typechecker (布尔 型 ， 默 认 是 on) 


这 个 选项 的 默认 值 是 on。HHVM 在 此 情况 下 将 会 拒绝 执行 任何 Hack 文 件 ， 除 非 它 找到 了 一 个 覆盖 对 应 文件 范围 的 Hack 类 型 检查 器 服务 进程 。 


在 实际 生产 过 程 中 ， 这 个 选项 应 该 关闭 ， 因 为 你 不 会 像 开 发 环境 之 中 那样 ， 运 行 一 个 Hack 类 型 检查 器 。 在 repo-authoritative 模 式 下 ， 它 将 会 自动 关闭 。 


hhvm.jit_enable_rename_function (布尔 型 ， 默 认为 off) 


这 个 选项 默认 是 off， 在 此 情况 下 ， 使 用 内 置 的 rename function () 将 会 触发 一 个 致命 错误 。 出 于 一 些 更 强大 优化 的 目的 ， 函 数 将 不 会 被 重 命名 。 所 以 如 果 你 对 这 个 功能 没有 依赖 的 话 ， 你 应 该 保持 这 
个 选项 值 为 off。 


hhvm.server.thread_count ( 整 型 ， 默 认为 CPU 核心 数 的 两 倍 ) 


这 个 选项 配置 了 在 服务 器 模式 下 (参见 8.2 节 ) ， 用 于 服务 Web 请 求 的 工作 线程 数量 。 对 于 完美 的 线程 数量 ， 这 里 比 并 没有 “ 放 之 四 海 而 皆 准 ”的 公式 。 在 更 复杂 的 方式 下 ， 这 依赖 于 应 用 程序 的 性 能 
点 ， 还 有 服务 器 的 CPU 及 内 存 规格 。 


不 使 用 异步 ( 见 第 6 章 的 内 容 ) 的 应 用 程序 将 最 有 可 能 从 比 默认 值 高 的 线程 数量 上 获 益 ， 因 为 线程 花费 大 量 的 空 等 待 时 间 ， 为 MO 请 求 而 等 待 。 一 个 好 的 起 点 可 能 是 核心 数 的 15 倍 。 


大 量 使 用 异步 的 应 用 使 用 默认 的 线程 数 就 可 以 了 ， 或 者 比 默 认 值 稍 高 。 异 步 可 以 帮助 HHVM 在 可 能 闲置 的 时 间 内 使 用 CPU。 


加 


为 峰值 时 的 利 上 


最 佳 的 调整 这 个 值 的 办 法 就 是 多 尝试 。 改 变 线程 数 ， 然 后 观察 对 CPU 和 内 存 利用 率 的 影响 。 随 着 你 提高 线程 数 ， 对 资源 的 利用 率 将 会 增加 。 可 以 在 网 络 繁忙 的 时 候 尝试 做 这 个 实验 。 
率 是 对 总 容量 最 好 的 检测 。 调 整 线程 数量 ， 以 提高 利用 率 到 定义 好 的 限定 (例如 70% 的 CPU) ， 然 后 停止 在 这 里 。 


HHVM 使 用 操作 系统 级 别 的 线程 ， 而 不 像 PHP-FPM 使 用 进程 。 增 加 HHVM 线 程 数 的 开销 非常 低 ， 所 以 增加 它 的 时 候 不 必 担心 。 


hhvm.source_root (字符 串 ， 默 认 值 是 HHVM 进 程 的 工作 目录 ) 


这 个 选项 仅 在 服务 器 模式 中 相关 ， 它 保存 着 被 服务 源码 的 根 目录 路 径 。 


8.2 ”服务 器 模式 


HHVM 有 两 种 主要 的 模式 : 命令 行 模式 和 服务 器 模式 。 命 令 行 模式 是 当 你 运行 类 似 hhvm test.php 的 命令 时 所 使 用 的 模式 。 它 立即 执行 给 定 的 脚本 ， 然 后 在 脚本 终结 后 退出 。 


服务 器 模式 就 是 你 用 于 服务 Web 请 求 的 。 在 这 种 模式 下 ，HHVM 进程 启动 后 并 不 立即 执行 任何 代码 。 当 它 通 过 FastCGI 收 到 请 求 的 时 候 ， 它 会 执行 对 应 的 代码 作为 回应 ， 然 后 保持 运行 直到 请 求 结束 。 
它 可 以 同时 处 理 多 个 请 求 。JIT 编 译 的 代码 是 保存 在 内 存 中 (在 译 码 缓存 中 translation cache) 的 ， 并 且 在 请 求 之 间 共 享 。 


可 以 使 用 命令 行 标志 位 -m server 来 启动 HHVM 的 服务 器 模式 : 


$ hhvm -m server -d hhvm.server.type=fastcgi -d hhvm.server.port=9000 


这 是 一 个 FastCGI 服 务 器 ， 所 以 9000 端 口 是 常 用 端口 。 


下 一 步 是 配置 一 个 Web 服 务 器 来 发 送 请 求 到 HHVM 的 FastCGI 服 务 器 上 。 你 可 以 使 用 任何 兼容 FastCGI 的 Web 服 务 器 软件 ， 例 如 Apache 或 者 nginx。 我 们 这 里 将 焦点 放 在 nginx 上 ， 因 为 它 更 易于 配 
置 ， 但 是 我 们 并 不 会 从 头 开始 配置 它 。 


发 送 FastCGI 请 求 到 HHVM 的 最 简化 配置 ， 是 使 用 像 下 面 这 样 的 位 置 指令 : 


location ~ \. (hh|Php)S { 
include fastcgi params; 
fastcgi param SCRIPT FILENAME $document root$fastcgi script name; 
fastcgi pass 127.0.0.1:9000; 

} 


fastcgi_params 指 代 一 个 标准 nginx 安 装 时 自 带 的 配置 文件 。 它 传递 请 求 的 参数 (HTTP 方 法 、 内 容 长 度 等 ) 到 HHVM。fastcgi_param 指 令 告诉 HHVM 要 执行 哪个 文件 。fastcgi_pass 指 令 意味 着 对 应 
的 请 求 将 要 传递 给 位 于 127.0.0.1 地 址 9000 端 口 的 FastCGI 服 务 器 。 这 个 配置 将 会 应 用 到 任何 以 .hh 或 者 .php 为 结尾 的 请 求 上 。 


全 wra pper 脚 本 
HHVM 的 命令 行 接口 可 能 非常 复杂 ， 所 以 包含 hhvm_wrapper 脚 本 的 包 应 运 而 生 ， 将 会 对 更 常见 的 选项 提供 更 方便 的 接口 。 
运行 hhvm_wrapper--help 来 查看 它 提供 的 选项 。 它 可 以 只 用 单一 命令 就 在 repo-authoritative 模 式 ( 见 8.4 节 ) 下 运行 一 个 脚本 : 


$ hhvm wrapper --compile test.php 


为 了 对 其 背后 的 原理 一 探究 竟 ， 可 以 添加 标志 位 --print-command 到 任何 hhvm_wtrappet 的 命令 行 。 它 将 会 输出 背后 的 HHVM 调 用 情况 ， 而 不 是 执行 对 应 的 命令 。 


8.3 JIT 热 身 


对 HHVM 服 务 器 最 开始 的 少数 请 求 会 比 其 余 的 慢 ， 因 为 它 必 须 在 执行 PHP 和 Hack 代 码 之 前 把 它们 编译 成 机 器 码 。 这 个 效果 非常 明显 ， 所 以 你 不 应 当 立 刻 把 一 个 新 设置 的 HHVM 服 务 器 应 用 到 生产 交易 
中 。 你 应 该 先 发 送 一 些 人 工 模拟 的 请 求 到 这 个 HHVM 服 务 器 上 ， 对 它 进 行 热身 。 


事实 上 ， 服 务 器 启动 时 并 不 会 编译 任何 代码 。 初 始 的 几 个 请 求 就 是 在 HHVM 的 字 节 码 解释 器 下 运行 的 。 原 理 就 是 ， 对 于 一 个 Web 服 务 器 来 说 ， 最 初 的 几 个 请 求 是 不 寻常 的 。 在 这 个 期 间 开始 初始 化 ， 还 
对 缓存 进行 了 填充 等 。 编 译 这 些 代码 路 径 对 整体 性 能 不 利 ， 所 以 一 旦 对 服务 器 进行 热身 ， 这 些 过 程 不 会 被 经 常 调用 。HHVM 还 利用 这 些 请 求 来 收集 一 些 代码 用 到 的 数据 类 型 分 析 的 工作 。 所 以 它 稍 后 可 以 更 
加 有 效 地 编译 。 你 可 以 使 用 选项 hhvm.jit_profile_interp_requests 来 调整 这 个 阅 值 。 


国运 一 特性 常常 泥 杂 着 人 们 对 HHVM 的 基准 判断 ， 因 为 开始 的 几 个 请 求 比 预 期 的 时 间 慢 。 事 实 上 ， 通 常 比 从 命令 行 里 面 运行 相同 的 脚本 更 慢 。 ( 当 运 行 命令 行 脚本 的 时 候 ，HHVM 每 一 次 都 编译 代码 。 


要 合理 地 测试 一 个 基于 JIT 的 执行 引擎 ， 你 必须 给 它 一 个 热身 的 时 期 。 因 为 这 样 做 有 些微 妙 ，HHVM 团 队 已 经 释放 了 一 个 工具 来 为 你 做 很 多 事情 。 使 得 对 服务 器 工作 负载 的 基准 判断 着 一 致 性 。 你 可 以 从 
GitHub 上 面 下 载 它 。 


发 送 热身 请 求 可 以 从 命令 行 脚本 或 者 其 他 类 似 的 地 方 ， 简 单 地 使 用 curl 这 个 命令 行 功能 。 对 于 最 好 的 结果 : 


“ 使 用 你 希望 在 产品 中 看 到 的 ， 能 够 代表 最 常见 请 求 的 混合 集合 。 例 如 ， 如 果 你 期 待 所 有 对 这 个 产品 请 求 中 的 40% 都 到 达 index.php， 那 么 你 的 40% 热 身 请 求 都 应 该 是 到 index.php 的 请 求 。 


“ 避免 并 行 发 送 多 个 热身 请 求 。 如 果 你 真 的 这 样 做 ， 并 不 会 出 现 什么 问题 。 但 是 对 于 JIT 编 译 器 来 说 ， 如 果 没 有 同时 工作 在 多 个 请 求 上 ， 它 往往 能 够 生成 更 好 的 代码 。 


最 终 ， 你 最 好 有 个 进程 脚本 用 于 服务 器 热身 ， 这 样 你 仅 执 行 一 个 命令 就 可 以 热身 了 。 但 是 在 初期 ， 你 还 是 需要 一 些 人 工 的 参与 。 要 实际 计算 出 用 于 热身 的 请 求 数 是 非常 微妙 的 。 这 主要 取决 于 你 的 程序 
本 身 。 


计算 出 热身 请 求 数 的 一 个 办 法 就 是 : 对 于 同一 个 端点 持续 保持 发 送 请 求 ， 直 到 你 可 以 看 到 一 致 的 响应 时 间 。 有 时 候 在 JIT 编 译 器 起 作用 后 (在 最 后 的 热身 请 求 之 后 ) ， 你 可 以 看 到 另外 一 个 性 能 上 的 跳 
跃 ， 因 为 在 档案 引导 优化 (profile-guided optimization，PGO) 下 ， 它 开始 对 一 些 代 码 再 次 进行 编译 。 当 PGO 开 始 的 时 候 ， 这 就 不 是 单一 的 热身 请 求 数量 的 阔 值 了 。 它 基于 代码 个 体 运行 的 频率 ， 所 以 你 
应 该 继续 运行 热身 请 求 ， 直 到 响应 时 间 趋 于 一 致 。 


你 还 可 以 使 用 管理 服务 器 ( 见 8.5 节 的 内 容 ) 来 监控 编译 的 代码 缓存 的 大 小 。 在 咱 编 译 器 开始 运行 时 ， 它 们 将 会 迅速 增长 ， 但 是 增长 速度 会 很 快 明显 降低 。 当 这 些 发 生 的 时 候 ， 服 务 器 才 是 真正 的 热身 。 


8.4 repo-authoritative 模 式 


默认 情况 下 ，HHVM 将 会 持续 对 PHP 和 Hack 的 源 文件 进行 检查 ， 来 确认 从 它 上 次 读 取 之 后 ， 对 应 的 文件 没有 被 修改 。 你 的 源 文件 被 部 署 为 产品 后 ， 这 个 检查 带 来 的 明显 开销 并 无 益处 ， 因 为 源 文件 不 太 
可 能 频繁 改动 了 。 


为 了 修复 这 个 问题 ，HHVM 提 供 了 一 个 repo-authoritative 模 式 。 在 这 种 模式 下 ， 你 可 以 提前 从 你 的 代码 库 里 面 创建 一 个 字 节 码 文件 (repo) ， 然 后 在 没有 源 文件 的 情况 下 把 它 发 布 为 产品 。 接 着 


HHVM 服 务 器 进程 从 repo 中 读 取 ， 而 不 会 去 检查 源 文件 系统 。 这 个 就 是 该 模式 名 称 的 由 来 : 该 字 节 码 文件 (repo) 是 “权威 (authoritative) ”的 。 


同时 为 了 减少 对 文件 系统 操作 的 需要 ，repo-authoritative 模 式 允许 HHVM 的 编译 器 做 出 本 来 不 能 做 的 重大 优化 。 因 为 要 保证 编译 器 可 以 看 到 在 进程 生命 周期 内 可 能 存在 的 所 有 代码 。 它 可 以 像 函 数 内 
联 一 样 正常 工作 ， 而 这 通常 来 说 是 不 可 能 的 。 


然而 ， 在 运行 时 不 能 引入 新 代码 的 缺憾 意味 着 : 在 repo-authoritative 模 式 下 ， 你 不 可 以 使 用 eval () 函数 或 者 create function () 函数 (因为 这 个 函数 实际 上 只 是 在 eval () 上 的 一 个 包装 ) 。 


8.4.1 创建 repo 


在 部 署 之 前 ， 你 必须 创建 repo。 你 可 以 通过 传递 一 些 标志 位 到 HHVM 中 来 达到 这 个 目的 。 我 们 还 是 从 最 基本 的 例子 入 手 ， 创 建 仅 包 含 一 个 文件 的 repo: 


$ hhvm --hphp -t hhbc -v AllVolatile=true test.php 


这 个 --hphp 标 志 位 [1 预示 着 我 们 希望 做 一 些 离线 操作 ， 而 不 是 要 执行 PHP 或 者 Hack 代 码 。-t hhbc 意 思 是 target HHBC， 就 是 说 我 们 希望 输出 字 节 码 。-v AllVolatile=true 开 启 了 一 个 选项 ， 用 于 禁 
一 个 需 小 心 正确 使 用 巴 的 非常 激进 的 优化 项 。 最 终 ， 我 们 传递 了 用 于 产生 字 节 码 的 文件 名 ， 在 本 例 中 只 有 一 个 文件 。 


这 个 操作 的 结果 就 是 在 当前 工作 目录 下 ， 产 生 了 一 个 名 为 hhvm.hhbc 的 文件 。 这 就 是 我 们 想 要 的 repo。 这 个 repo 


它 B], 


有 实 上 仅仅 是 一 个 SQLite3 的 数据 库 文件 ， 所 以 你 可 以 使 用 sqlite3 的 命令 行 工具 来 检测 


在 实践 当中 ， 如 果 在 命令 行 中 需要 包含 所 有 的 源 文 件 名 称 ， 这 会 是 非常 可 怕 的 事情 。 所 以 你 还 可 以 准备 一 个 文本 文件 ， 文 件 内 容 是 需要 被 包含 的 源码 文件 名 ， 每 行 一 个 文件 名 ，HHVM 可 以 接受 这 个 列 
表 文 件 的 名 称 作为 参数 。 假 设 我 们 已 经 有 了 叫做 files.txt 的 文件 ， 内 容 如 下 : 


lib/a.php 
1ib/b.php 
Index.php 


然后 告诉 HHVM 使 用 这 个 列表 作为 它 的 输入 项 目 : 


$ hhvm --hphp -t hhbc --input-list files.txt 


在 创建 这 个 repo 的 时 候 ，repo 对 传递 到 HHVM 之 中 的 所 有 文件 路 径 进 行 捕获 。 这 些 路 径 将 会 组 成 “虚拟 文件 系统 ”， 里 面包 含 HHVM 从 这 个 repo 中 运行 得 到 的 各 种 各 样 的 文件 。 具 体 来 说 ， 当 HHVM 
从 这 个 repo 中 运行 的 时 候 ，Web 服 务 器 给 它 某 个 路 径 的 请 求 。 假 设 是 /someyfile.php，HHVM 将 会 在 repo 中 寻找 这 个 文件 ， 寻 找 的 规则 就 是 ， 这 个 文件 在 repo 被 创建 的 时 候 ， 路 径 是 /someyfile.php。 


鉴于 上 述 内 容 ， 如 果 你 从 路 径 创 建 repo， 这 个 路 径 是 相对 于 被 部 署 的 Web 服 务 器 的 文档 根 目录 ， 事 情 就 会 变 得 非常 简单 。 然 而 ， 这 主要 取决 于 你 在 Web 服 务 器 级 别 上 想 做 多 少 路 径 改写 。 


8.4.2 ”部署 repo 


把 hhvm.hhbc 文 件 复制 到 你 的 生产 服务 器 上 ， 你 不 需要 复制 源 文 件 ， HHVM 可 以 在 没有 它们 的 情况 下 运转 。 如 果 你 配置 了 你 的 Web 服 务 器 用 于 查找 文件 系统 ， 来 最 终 决定 对 于 给 定 的 请 求 如 何 处 理 
(这 是 很 常见 的 ) ， 你 可 能 需要 复制 你 的 源 文件 。 然 而 ， 你 可 以 在 目录 结构 中 使 用 空 的 文件 来 模拟 真实 的 代码 库 ， 这 对 于 Web 服 务 器 来 说 足够 了 。 


你 创建 repo 的 HHVM 和 你 运行 repo 的 HHVM 必 须 保 持 一 致 。repo 向 前 向 后 都 不 兼容 。 当 创建 一 个 repo 的 时 候 ，HHVM 在 它 里 面 谋 入 一 个 repo schema ID， 这 对 于 每 个 HHVM 版 本 来 说 是 唯一 的 。 当 
在 运行 时 中 使 用 repo 的 时 候 ，HHVM 会 拿 repo 的 schema ID 和 它 自己 版 本 对 比 ， 如 果 schema ID 并 不 匹配 ， 它 将 不 会 使 用 这 个 repo。 


你 在 那里 放置 这 个 repo 文 件 没 有 关系 ， 只 要 HHVM 进 程 能 够 读 取 到 它 即 可 。 还 记得 先前 提 到 的 “虚拟 文件 系统 ” 吗 ? 在 repo-authoritative 模 式 下 ，HHVM 从 来 不 会 关心 真实 的 文件 系统 ， 只 关心 repo 
的 内 容 。 这 就 意味 着 hhvm.server.source_root 的 设置 在 repo-authoritative 模 式 下 没有 什么 用 途 。 


这 里 有 两 个 相关 的 配置 选项 : 一 个 告诉 HHVM 使 用 repo-authoritative 模 式 ， 另 外 一 个 告诉 它 repo 文 件 的 具体 位 置 。 这 些 都 需要 在 你 的 INI 文 件 中 放置 (请 用 正确 的 路 径 名 称 蔡 代 ) : 


hhvm.repo.authoritative = 工 
hhvm. repo.central.path = /path/to/hhvm.hhbc 


中 一 个 历史 神器 。 
[中 这 个 优化 项 目 被 默认 开启 ， 是 有 些 玖 忽 了 。 
[3] 这 里 没有 能 够 看 懂 的 代码 ， 但 是 这 里 有 可 读 的 元 数据 。 


8.5 ”管理 服务 器 


在 服务 器 和 守护 进程 模式 下 ，HHVM 提 供 了 一 种 机 制 用 于 观察 和 控制 正在 运行 的 服务 器 进程 。 这 个 进程 监听 一 个 隔离 的 端口 ， 通 过 这 个 端口 ， 你 就 可 以 用 HTTP 请 求 来 发 布 命令 了 。 这 个 功能 叫做 
admin server。 它 提供 了 大 量 的 命令 。 我 们 在 这 里 将 履 盖 一 些 基 本 使 用 点 ， 而 不 会 面面俱到 。 


这 个 admin server 默 认 是 关闭 的 。 你 可 以 通过 对 它 指定 一 个 用 于 监听 的 端口 号 来 开启 ， 具 体 使 用 哪个 端口 没有 关系 ， 只 要 是 空闲 可 用 的 端口 即 可 ，HHVM 会 绑 定 到 这 个 端口 。 你 应 该 同时 设置 一 个 密 
码 。 你 将 会 在 对 admin server 的 每 次 请 求 中 给 出 这 个 密码 : 


hhvm.admin server.port = 9001 
hhvm.admin server.password = 9UejLK2jVhy 


你 需要 设置 你 的 Web 服 务 器 来 监听 一 个 新 的 端口 ， 并 且 对 到 admin server 端 口 的 请 求 作为 FastCGI 请 求 进行 转发 。 在 前 面 的 例子 中 ,我 们 将 假设 选取 了 一 个 15213 的 端口 作为 Web 服 务 器 监听 的 端口 。 


全,admin server 潜 在 是 非常 危险 的 ， 这 也 是 为 什么 默认 不 开启 它 。 千 万 不 要 不 使 用 密码 开启 它 ， 而 且 要 使 用 定期 轮换 的 强 密码 ， 并 且 不 能 把 它 的 端口 暴露 到 互联 网 上 。 


一 旦 这 个 HHVM 服 务 器 进程 开启 ， 你 可 以 使 用 curl 命 令 行 功能 (或 者 一 个 Web 浏 览 器 ) 来 对 它 发 送 命 令 。 在 这 些 例 子 中 ， 我 们 假设 在 和 HHVM 服 务 器 进程 相同 的 机 器 上 运行 curl， 并 且 admin server 的 
密码 也 是 我 们 早期 配置 好 的 那个 。 


对 admin server 发 送 一 个 到 /的 请 求 ， 将 会 展示 一 个 


可 能 的 命令 列表 的 帮助 信息 。 你 想得到 帮助 的 时 候 并 不 需要 提供 密码 : 


$ curl http://localhost:15213/ 


/stop: 
instance-id 
/translate: 
stack 
build-id 

bare 
/build-id: 
/instance-id: 
/compiler-id: 
/repo-schema: 
/check-load: 
/check-queued: 
/check-health: 
/check-ev: 
/check-pP1-1oad: 


人 
项 ， 如 果 指 明 ， 实 例 ID 必 须 匹 配 
秆 "stack' 参 数 中 十 六 进 制 编码 栈 
必 填 项 ， 需 要 被 翻译 的 栈 跟踪 信息 
项 ， 如 果 指 明 的 话 ，build ID 必须 匹配 
可 选项 ， 是 否 要 展示 frame 坐 标 
返回 从 命令 的 builq ia 
从 命令 行 传递 的 实例 id 
是 这 个 app 的 编译 器 id 
回 被 这 个 app 所 使 用 的 repo 的 schema id 
六 舌 用 于 处 理 请 求 的 线程 数量 
队列 中 等 待 处 理 的 http 请 求 数量 
返回 包含 基本 的 1oad/usage 状 态 的 json 串 
被 libevent 激 活 的 http 请 求 数量 
正在 激活 以 处 理 请 求 地 Pagelet 线程 数量 


/check-pl-queued: 队列 中 正在 等 待 处 理 的 pagelet 请 求 数量 
/check-mem: 在 一 个 日 ; 件 中 报告 内 存 简要 状况 
/check-sql: 报告 SQL 


后 Sql 
/check-sat 有 多 少 卫星 进程 正在 激活 使 用 ， 用 于 处 理 请 求 和 并 
http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/.. 


每 个 命令 都 是 一 个 路 径 值 ， 它 可 以 添加 到 你 的 admin server 请 求 之 中 。 对 于 这 些 请 求 中 的 任何 一 个 


令 ， 这 将 会 展示 HHVM 字 节 被 构建 的 源 Git 的 修订 版 本 号 。 


E 在 等 待 处 理 的 队列 


. 省 略 更 多 的 细节 http://www.hzcourse.com/resource/readBook?path=/openre: 


， 你 都 必须 通过 GET 请 求 的 auth 参 数 ， 提 供 你 在 admin server 中 配置 好 的 密码 。 例 如 compiler-id 命 


$ curl http://localhost:15213/compiler-id?auth=9UejLK2jVhy 
tags/HHVM-3.6.2-0-glle5cecb678453d47ce2cea83997a2c5703abb41 


在 help 输 出 中 缩 进 的 项 目 ， 例 如 在 /stop 命 令 下 的 instance-id， 就 是 你 


命令 能 够 提供 的 GET 参 数 名 称 : 


$ curl http://localhost:15213/stop?auth=9UejLK2jVhy&instance-id=INSTANCEID 


如 果 你 输入 了 错误 的 密码 ， 那 么 admin server 将 会 返回 Unauthorized 的 文本 。 


HHVM 配 备 着 叫做 hphpd 的 交互 调试 器 。 为 使 你 对 这 个 概念 更 加 熟悉 ， 


程序 (例如 ， 当 执行 进入 某 个 特定 的 函数 ， 或 者 到 达 某 个 特定 的 代码 行 时 ) 。 


第 9 章 ”hphpd: 交互 式 调 试 器 


这 里 对 其 做 个 简要 介绍 : 交互 式 调试 器 就 是 可 以 让 你 控制 其 


他 程序 并 且 查看 它们 状态 的 程序 。 可 以 设置 在 特定 的 点 暂停 被 控制 的 


可 以 在 执行 期 间 查看 每 个 变量 的 值 ， 甚 至 在 一 些 情况 下 修改 这 些 值 。 对 调试 一 个 大 型 复杂 的 程序 来 说 ， 相 较 使 


断 试 错 的 工作 流 模式 ， 这 种 交互 式 调试 器 是 非常 强大 的 工具 ， 它 们 可 以 大 幅 提高 易 用 性 及 效率 。 


hphpd 对 于 PHP 和 Hack 都 是 一 个 应 答 式 编 程 器 (read-eval-print loop，REPL) 


如 果 你 还 使 用 像 GDB 或 者 LLDB 之 类 的 交互 式 调试 器 ， 你 将 会 发 现 hphpd 和 它们 很 相似 。 


发 现 之 旅 了 。 


。 可 以 在 代码 库 的 上 下 文中 (这 样 就 可 以 使 


实 上 ， 你 可 能 甚至 不 需要 阅读 本 章 的 内 容 ， 你 或 许可 以 使 


在 本 章 中 ， 我 们 将 会 看 到 如 何 使 用 hphpd 来 调试 脚本 和 Web 应 用 ， 如 何 对 其 进行 配置 ， 以 及 如 何 从 中 获得 最 大 益处 。 


9.1 开始 入 门 


可 以 通过 在 shell 命 令 行 里 面 输入 hhvm-m debug 来 启动 hphpd。 然 而 并 不 会 执行 任何 代码 ， 


printf 调 试 、 不 


你 的 库 函 数 了 ) 交互 式 输 入 PHP 和 Hack 代 码 ， 来 尝试 运行 小 段 的 代码 。 


HHVM 将 会 显示 一 个 欢迎 信息 ， 


并 进入 调试 器 提示 模式 : 


hphpd 的 交互 式 帮助 命令 help 就 可 以 开始 我 们 的 


$ hhvm -m debug 
Welcome to HipHop Debugger! 
Type "help" or "?" for a complete list of commands. 


Note: no server specified, debugging local scripts only. 
If you want to connect to a server, launch with "-h" or use: 
[m] achine [clonnect <servername> 


hphpd> 


不 管 你 敲 什 么 命令 ， 它 们 都 会 出 现在 最 后 一 行 输出 的 hphpd> 标 志 后 面 ， 就 像 在 shell 命 令 行 里 面 一 样 。 这 就 是 你 输入 hphpd 命 令 的 地 方 。hphpd 的 命令 行使 


命令 历史 ， 并 且 支 持 像 Emacs 键 绑 定之 类 的 功能 ， 还 可 以 使 用 向 下 和 向 上 的 方向 键 来 查看 输入 的 命令 历史 。 


现在 让 我 们 在 hphpd 中 开始 学 习 最 有 用 的 命令 ， 在 命令 行 提示 中 简单 输入 help 或 者 “? ”。 


控制 台 将 会 输出 下 面 的 命令 列表 : 


GNU Readline 库 ， 所 以 它 能 够 记 住 你 的 


hphpd> help 
一 一 Session Commands 


m] achine connects to an HHVM server 
七 ]hread Switches between different threads 
slet various configuration options for hphpd 
qluit quits debugger 

Progran Row Control 一 一 一 一 
b]reak sets/clears/displays breakpoints 
e]xception catches/clears exceptions 
rlun starts over a program 
wetejl=-C> breaks program execution 
clontinue * continues program execution 
sltep a steps into a function call or an expression 
卫 ] ext steps over a function call or a line 
olut , steps out a function call 

Display Commands 一 一 

plrint prints a variable's value 
wlhere displays stacktrace 
ulp goes up by frame (S) 
dj]own goes down by frame(s) 
fl]rame goes to a frame 


vjariable lists all local variables 

gl]lobal lists all global variables 

kl]onstant lists all constants 
a ton Conmmde: = 

@ evaluates one line of PHP code 

本 prints right-hand-side's value, assigns to $ 
${name}= assigns a value to left-hand-side 加 
<?]php starts input of a block of PHP code 

?> ends and evaluates a block a PHP code 
albort aborts input of a block of PHP code 

z]end evaluates the last snippet in PHP5 

Documentation and Source Code 一 一 

ijnfo displays documentations and other information 
汕 ] 六 各 想 ， 深 displays source codes 

hjelp ** displays this help 

全 displays this help 
— Shell and Extended Commands 一 一 一 

! {cmd} executes a shell command 

& {cmd} records and replays macros 

x {cmd} extended commands 

y {cmd} user extended commands 


* These commands are replayable by just hitting return. 
**# Type "help help" to get more help. 


在 一 些 命令 的 开头 位 置 ， 有 用 方 括号 括 起 来 的 字符 。 这 些 字符 意味 着 你 可 以 简单 地 通过 输入 这 个 字符 来 调用 对 应 的 命令 。 


你 可 以 键入 help 和 你 想 要 了 解 的 命令 名 字 ， 来 获得 更 加 详细 的 帮助 


hphpd> help variable 
Variable Command 


[vjariable lists all local variables on stack 
[vjariable {text} full-text search local variables 


This will print names and values of all variables that are currently 
accessible by simple names. Use '[wlhere', '[ulp {num}', '[dljown {num}', 
'[flrame {index}' commands to choose a different frame to view 
variables at different level of the stack. 


Specify some free text to print local variables that contain the text 
either in their names or values. The search is case-insensitive and 
string-based. 


当 获 取 一 个 命令 帮助 时 ， 你 也 可 以 使 用 相应 命令 的 简写 名 字 。help v 和 help variable 功 能 相同 。 


一 些 命令 行 有 子 指令 ， 这 些 子 指令 可 以 选择 该 命令 的 不 同行 为 。 例 如 ， 除 此 之 外 ，break 命 令 可 以 


来 显示 所 有 的 断 点 (break list) 或 者 删除 这 些 断 点 (break clear) 


很 多 命令 还 有 实 参 ， 可 以 通过 在 命令 自身 后 面 的 调试 器 提示 中 输入 这 些 实 参 进 行 实 参 传递 ， 它 们 之 间 使 用 空格 分 隔 。 这 和 在 shell 命 令 行 中 传递 实 参 非常 类 似 。 


可 以 通过 quit 命 令 或 者 直接 按 Ctrl-C 组 合 键 退出 hphpd。 (执行 代码 的 时 候 ， 按 Ctrl-C 组 合 键 将 会 暂停 执行 ， 把 你 带 回 到 调试 器 提示 中 。) 


9.2 代码 执行 


可 以 使 用 @ 命 令 来 对 Hack 代 码 进行 执行 。 在 @ 和 换行 之 间 输 入 的 任何 东西 都 会 被 执行 ， 换 行 符 标志 着 


这 个 命令 内 容 的 结束 。 它 可 以 是 一 条 或 者 多 条 语句 (你 不 需要 在 结 


。 我 们 将 会 对 每 


尾 加 上 分 号 ) 


AAA， 全 
个 命令 的 子 指令 


hphpd> @echo "hello\n" 
hello 


hphpd> @function speak() { echo "speaking\n"; } 


hphpd> @speak () 
speaking 


hphpd> Gecho "hello "; echo "world\n" 
hello world 


Ahphpd 在 每 个 提示 前 并 没有 留 一 个 空 行 ， 这 里 出 于 易 读 性 的 考虑 ， 对 它们 添加 了 空 行 。 


还 可 以 使 用 等 号 命令 输出 一 个 表达 式 的 值 : 


hphpd> = 1 + 2 
3 


hphpd> = "hello ' . 'world' 
"hello world" 


在 每 个 等 号 命令 执行 后 ， 计 算得 到 的 值 会 存储 在 变量 $_ 中 : 


hphpd> = 'beep' 
"beep" 


hphpd> Gecho $_ 
beep 


可 以 通过 在 命令 中 直接 输入 赋值 语句 把 一 个 值 赋值 给 变量 。 还 可 以 使 用 @ 来 做 这 样 的 事情 。 赋 值 是 一 个 如 此 常见 的 操作 ， 所 以 它 在 调试 器 命令 语法 中 是 个 特例 : 


hphpd> Shello = 'hello' 


hphpd> = $hello 
"hello" 


最 后 ， 这 里 有 个 可 以 让 你 一 次 性 观察 所 有 局 部 变量 的 命令 ， 它 比重 复 使 用 = 方便 快捷 多 了 。 这 个 命令 就 是 variable。 它 将 输出 所 有 局 部 变量 的 名 称 和 值 。 


hphpd> Snums = array (10, 20, 30) 
hphpd> $num = $nums[0] 

hphpd> $count = count ($nums) 
hphpd> variable 

$count = 3 

$num = 10 

Snums = Array 


可 以 传递 一 个 实 参 到 variable 命 令 中 ， 对 将 要 输出 的 局 部 变量 进行 过 滤 。 任 何 名 字 中 包含 该 命令 实 参 的 变量 将 作为 子 字符 串 输出 。 继 续 前 面 的 例子 : 


hphpd> variable num 
$num = 10 
$nums = Array 


( 


[0] => 10 
[1] => 20 
[2] => 30 


一 旦 我 们 开始 执行 和 调试 实际 代码 ， 这 个 命令 将 会 更 加 有 用 。 


9.3 ”执行 环境 


目前 我 们 看 到 的 例子 都 运行 在 初始 为 空 的 执行 环境 中 ， 没 有 任何 源 文 件 被 加 载 []。 当 使 用 真实 代码 库 时 ，hphpd 乐 趣 的 使 用 方法 才 会 体现 。 


hphpd 可 以 工作 在 两 种 模式 下 : 本 地 和 远程 。 本 地 模式 意味 着 调试 器 工作 在 它 自己 进程 中 的 PHP/Hack 环 境 下 。 远 程 模式 意味 着 它 工作 的 PHP/Hack 环 境 在 一 个 不 同 的 进程 中 ， 这 是 一 个 服务 器 模式 或 
者 守护 进程 模式 的 HHVM 进 程 。 其 他 的 进程 可 能 在 不 同 的 机 器 上 ， 但 这 不 是 必需 条 件 。 连 接 到 localhost 是 使 用 远程 模式 最 常见 的 方式 。 


可 以 通过 调试 器 提示 来 分 辩 hpphpd 工 作 在 什么 模式 下 。 如 果 它 仅仅 显示 hphpd> ， 那 么 它 在 本 地 模式 下 。 如 果 它 显示 了 其 他 什么 东西 ， 例 如 连接 的 主机 名 称 ， 那 么 就 是 在 远程 模式 下 。 


当 你 仅仅 把 hphpd 用 作 REPL 或 者 调试 一 个 脚本 的 话 ， 那 么 你 将 使 用 本 地 模式 。 远 程 模式 是 用 于 调试 Web 应 用 的 ， 你 将 会 连接 到 运行 你 应 用 的 HHVM 进 程 之 中 。 


9.3.1 本 地 模式 


当 你 没有 使 用 实 参 就 启动 hphpd 的 时 候 ， 就 像 简单 的 hhvm-m debug， 它 将 会 运行 在 本 地 模式 下 ， 并 不 会 加 载 其 他 程序 。 当 要 对 独立 的 小 段 PHP 或 者 Hack 代 码 进行 测试 时 ， 这 种 模式 才 是 有 用 的 。 此 
时 ， 你 源 文件 中 的 任何 代码 都 不 会 生效 。 


可 以 把 一 个 文件 名 字 作 为 实 参 来 启动 hphpd， 例 如 hhvm-m debug test.php。 这 将 会 加 载 这 个 文件 并 且 准 备 去 运行 它 。 当 你 在 hphpd 中 执行 run 命 令 时 ， 它 将 会 从 头 开始 执行 test.php。 这 个 过 程 和 你 
在 命令 行 里 面 执 行 hhvm test.php 非 常 类 似 。 


这 里 是 test.php 的 内 容 : 


<?hh 


echo "hello\n"; 


我 们 将 在 hphpd 中 对 其 进行 加 载 并 运行 。 


$ hhvm -m debug test.php 
Welcome to HipHop Debugger! 
Type "help" or "?" for a complete list of commands . 


Program test.php loaded. Type ' [rlun' or '[clontinue' to go. 
hphpd> run 

hello 

Program test.php exited normally. 

hphpd> 


如 果 你 再 一 次 输入 run 命 令 ， 这 个 程序 将 会 再 次 从 头 开始 执行 。 


运行 过 一 次 程序 后 ， 这 个 程序 中 的 定义 的 任何 函数 、 类 等 ， 都 将 会 在 上 下 文中 生效 。 可 以 使 用 @ 和 = 语法 来 调用 它们 ， 并 不 要 求 这 个 程序 实际 上 正在 运行 。 


这 里 是 个 新 的 test.php: 


<?hh 


function func() { 
echo "hello\n"; 
} 


请 注意 这 里 并 没有 任何 项 层 代 码 ， 所 以 仅仅 运行 这 个 脚本 并 不 会 有 任何 可 见 的 效果 。 我 们 仅仅 通过 运行 它 一 次 来 加 载 对 应 的 函数 ， 然 后 再 使 


导 


hphpd> run 
hphpd> = func() 
hello 


hphpd> 


现在 ， 如 果 你 对 这 个 文件 做 出 改动 ， 再 次 执行 run 命 令 将 会 从 文件 系统 中 再 次 加 载 该 文件 ， 那 么 你 就 可 以 及 时 看 到 你 改动 的 效果 了 。 


9.3.2 ”远程 模式 


为 了 使 用 hphpd 的 远程 模式 ， 你 需要 一 个 服务 器 模式 或 者 守护 进程 模式 的 HHVM 进 程 用 于 配合 调试 。 这 方面 的 细节 可 以 参考 第 8 章 的 内 容 。 这 个 进程 需要 保持 它 的 调试 服务 器 开启 ， 这 样 hphpd 才 能 
连接 到 它 。 它 还 需要 开启 沙 盒 模式 (sandbox mode) ， 关 于 这 一 点 我 们 随后 再 进行 解释 。 这 里 是 你 将 会 用 到 的 配置 选项 列表 ， 它 们 是 INI 格 式 的 : 


hhvm.sandbox.sandbox mode = 1 
hhvm.debugger.enable debugger = 1 


hhvm.debugger.enable debugger server = 1 


默认 情况 下 ， 这 个 进程 将 会 对 端口 8089 上 所 有 进入 的 调试 器 连接 进行 监听 。 可 以 通过 选项 hhvm.debugger.port 来 进行 配置 。 


一 旦 你 有 个 合适 的 服务 器 进程 ， 就 可 以 通过 命令 行 实 参 -h 加 上 要 连接 的 主机 名 ， 来 启动 hphpd 的 远程 模式 。 


$ hhvm -m debug -h localhost 
Welcome to HipHop Debugger! 
Type "help" or "?" for a complete list of commands. 


Connecting to localhost:8089http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
Attaching to oyamauchi's default sandbox and pre-loading, please waithttp://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


localhost> 


这 个 命令 行 提示 显示 ， 我 们 已 经 成 功 连接 到 了 对 应 的 机 器 。 你 可 以 使 用 machine 的 disconnect 子 指令 来 退出 远程 模式 ， 进 入 本 地 模式 。 


你 还 可 以 通过 使 用 machine 命 令 的 connect 子 指令 再 次 从 本 地 模式 进入 远程 模式 。 


hphpd> machine connect localhost 
Connecting to localhost:8089http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
Attaching to oyamauchi's default sandbox and pre-loading, please waithttp://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


localhost> 


现在 让 我 们 来 看 看 刚才 提 到 的 沙 盒 概念 。 在 HHVM 中 ， 沙 盒 就 是 一 组 包含 文档 根 目 录 和 日 志文 件 路 径 的 配置 选项 。HHVM 可 以 在 单独 的 服务 器 模式 进程 中 支持 多 重 沙 盒 。 本 质 上 就 是 运行 单独 进程 为 多 


个 不 同 的 Web 应 用 提供 服务 向 。 (出 于 安全 目的 进行 代码 隔离 时 ， 你 可 能 听 过 术语 “ 沙 盒 ”。HHVM 中 这 个 术语 的 使 用 和 这 完全 没有 关系 。) 


配置 多 重 沙 盒 非常 复杂 ， 而 且 有 点 超出 我 们 这 里 讨论 的 范围 。 和 这 里 相关 的 事情 就 是 ，hphpd 为 了 调试 一 个 服务 器 模式 的 HHVM 进 程 ， 就 必须 打开 这 个 沙 盒 模式 。 当 你 连接 到 一 个 服务 器 模式 的 HHVM 
进程 时 ， 必 须 选 择 要 附加 到 哪 一 个 沙 盒 之 上 。 


当 你 连接 到 一 个 服务 器 模式 的 进程 时 ， 会 附加 到 一 个 仿真 的 沙 盒 (dummy sandbox) ， 这 是 一 个 专门 为 调试 器 创建 的 沙 盒 。 它 没有 文档 根 目录 设 定 ， 所 以 它 没 有 加 载 任何 代码 。 它 存在 的 唯一 目的 就 
是 ， 在 调试 器 提示 中 为 代码 执行 提供 一 个 PHP/Hack 的 环境 。 这 和 没有 任何 程序 加 载 的 hphpd 的 本 地 模式 非常 类 似 。 


使 用 machine 命 令 的 子 指令 list 就 可 以 看 到 这 个 服务 器 上 的 所 有 沙 盒 : 


localhost> machine list 
1 oyamauchi's default sandbox at /oyamauchi/www/ 
2 _ builtin's default sandbox at /home/oyamauchi/test-site/ 


列表 中 的 第 一 个 入 口 就 是 上 述 的 仿真 沙 盒 (注意 它 的 路 径 可 能 是 很 荒 缪 的 ， 事 实 上 它 并 不 经 常 使 用 ) 。 第 二 个 入 口 是 个 真实 的 入 口 ， 代 表 这 个 服务 器 用 来 处 理 网 络 请 求 的 沙 盒 配 


本 自从 这 个 服务 器 运作 起 来 ， 如 果 它 并 没有 处 理 任何 请 求 ， 那 么 这 个 真实 的 沙 盒 并 不 会 显示 出 来 。 如 果 你 运行 machine list 并 仅 看 到 仿真 的 沙 盒 ， 请 尝试 对 这 个 服务 器 做 个 网 络 请 求 ， 以 显示 真实 的 沙 盒 


i 


言 息 
让 


你 可 以 通过 使 用 attach 子 指令 ， 加 上 沙 盒 的 编号 作为 实 参 ， 附 加 到 真实 的 沙 盒 上 : 


localhost> machine attach 2 
Attaching to _ builtin's default sandbox at /home/oyamauchi/test-site/ and 
pre-loading, please waithttp://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/O0EBPS/Text/... 


localhost> 


现在 你 已 经 加 载 了 Web 应 用 的 代码 ， 处 于 正确 的 上 下 文中 了 。 你 可 以 设置 断 点 ( 见 下 一 节 ) 和 查看 代码 ( 见 9.5 节 ) 了 ，hphpd 将 会 在 这 个 代码 库 上 进行 相关 操作 。 


[由 可 以 使 用 @ 命 令 来 执行 include 或 其 类 似 语句 。 
D] 这 个 功能 被 特别 地 研发 ， 用 于 支持 Facebook 的 网 站 开发 (在 这 里 ， 多 个 开发 者 共享 同一 台 开 发 机 器 ) ， 它 的 很 多 方面 都 还 是 Facebook 特 制 的 ， 这 可 能 和 现实 世界 的 真实 情况 不 很 搭配 。 未 来 这 个 问题 将 会 


得 到 政 善 。 


9.4 ”使 用 断 点 


当 对 某 个 程序 进行 调试 的 时 候 ， 断 点 就 是 这 样 一 种 条 件 : 将 会 导致 调试 器 暂停 程序 的 执行 ， 然 后 返回 调试 器 提示 中 。 这 里 有 很 多 种 可 以 用 作 断 点 的 条 件 : 
“ 当 执行 到 达 某 个 特定 文件 的 特定 行 上 时 
“ 当 执 行进 入 某 个 特定 的 函数 或 方法 上 时 


“ 当 对 菜 个 特定 URL 的 Web 请 求 开始 或 结束 时 


让 我 们 开始 一 个 简单 的 例子 。 设 想 有 这 样 一 个 文件 ， 叫 做 test.php: 


<?hh 
function func (string $first, string $second): void { 
echo $first . "\n"; 
echo $second . "\n™; 
} 
func('one', 'two'); 
我 们 将 会 运行 nphpd， 并 且 在 两 个 echo 语 句 间 设 置 断 点 。 为 了 设置 一 个 断 点 ， 你 需要 使 用 hphpd 的 break 命 令 ， 然 后 附带 上 汤 点 条 件 []。 在 这 个 案例 中 ， 我 们 将 在 第 五 行 设置 一 个 断 点 ， 这 行 包含 着 第 


二 个 echo 语 句 ， 当 你 在 某 一 行 设 置 断 点 的 时 候 ， 在 该 行 任意 代码 被 执行 之 前 ， 执 行 过 程 就 会 暂停 。 我 们 依次 输入 文件 名 称 、 一 个 冒号 、 行 号 (注意 没有 空格 ) ， 就 可 以 指明 断 点 位 置 了 : 


$ hhvm -m debug test.php 
hphpd> break test.php:5 
hphpd> run 


one 


Breakpoint 1 reached at func() on line 5 of /home/oyamauchi/test.php 


4 echo $first . wy 
5* echo $second . "\n"; 
6 } 

hphpd> 


这 个 脚本 开始 执行 ， 输 出 one， 然 后 暂停 。 调 试 器 将 会 输出 执行 暂停 位 置 附近 的 代码 ， 然 后 用 一 个 星 号 标记 对 应 的 断 点 行 。 (如 果 你 的 终端 支持 ， 这 个 输出 也 会 被 彩色 标记 ， 把 对 应 的 行 高 亮 显 示 。) 
请 注意 two 还 没有 被 输出 。 


调试 器 提示 是 可 见 的 ， 意 味 着 调试 器 正在 等 待 进一步 的 指令 。 你 可 以 使 用 variable 以 及 相关 的 执行 命令 来 查看 相关 程序 状态 ， 还 可 以 设置 更 多 的 断 点 ， 步 进 执行 ， 或 者 恢复 正常 执行 。 你 将 会 在 本 节 的 
剩余 部 分 学 习 到 如 何 做 这 些 操作 。 


9.4.1 设置 断 点 


我 们 已 经 学 习 了 在 某 个 特定 文件 的 特定 行 设置 断 点 的 语法 。 这 里 将 学 习 对 给 定 函 数 设置 断 点 的 语法 : 


hphpd> break my_function () 
Breakpoint 1 set upon entering my function() 


无 需 考虑 函数 有 什么 样 的 形 参 ， 你 只 需要 总 在 函数 名 后 面 放置 一 组 空 的 圆 括号 即 可 。 


你 也 许 会 看 到 一 条 “在 这 个 函数 加 载 之 前 ， 执 行 不 会 被 打 断 ”的 消息 。 这 通常 没有 什么 好 担心 的 ， 因 为 随 着 代码 执行 和 文件 加 载 ， 调 试 器 将 会 观察 给 定名 字 的 函数 被 加 载 进来 。 当 发 现 的 时 候 ， 它 将 会 
保证 这 个 断 点 得 到 有 效 设 置 。 


为 了 对 一 个 方法 设置 断 点 ，break 命 令 的 实 参 组 成 为 : 类 名 、 两 个 冒号 、 方 法 名 称 、 一 对 空 的 圆 括号 : 


hphpd> break MyClass: :myMethod () 
Breakpoint 1 set upon entering MyClass::myMethod () 


这 个 “类 加 方法 名 ”的 组 合 从 词法 上 已 经 解决 了 问题 。hphpd 根 本 就 没有 考虑 过 继承 和 trait 的 事情 。 换 句 话说 ， 如 果 一 个 方法 特别 用 给 定 的 名 称 写 在 了 类 的 定义 之 中 ， 断 点 将 会 设置 在 这 里 。 如 果 这 个 
方法 在 类 使 用 的 trait 中 被 定义 ,或 者 从 祖先 类 那里 继承 而 来 ， 这 个 断 点 不 会 被 设置 。 


当 调 试 一 个 网 络 请 求 时 ， 远 程 模式 断 点 触发 器 的 最 终 形态 是 很 特别 的 。 你 可 以 在 网 络 请 求 的 开始 或 者 结束 的 时 候 设置 断 点 。 也 可 以 在 通过 register_ shutdown_function () 注册 的 shutdown 函 数 进程 
开始 的 位 置 设置 。 对 应 的 语法 分 别 是 break start、break end 以 及 break pspI。 


我 们 可 以 使 用 一 个 URIB] 的 path 部 分 对 它们 三 个 命令 进行 修改 。 这 种 情况 下 ， 断 点 将 仅仅 在 网 络 请 求 到 这 个 路 径 的 时 候 才 会 被 触发 : 


hphpd> break start /something/something.php 
Breakpoint 1 set start of request when request is /something/something.php 


请 注意 ， 将 被 检查 的 URL 是 原始 请 求 的 URI， 这 个 值 存储 在 $_SERVER['REQUEST_URI"] 中 。 这 并 不 是 结束 调用 的 PHP 或 者 Hack 文 件 的 路 径 。 


断 点 表达 式 和 条 件 


前 面 所 述 的 任何 断 点 都 有 一 个 Hack 表 达 式 相关 联 。 并 且 hphpd 每 次 碰 到 断 点 的 时 候 都 要 执行 一 下 表达 式 。 最 常见 的 用 法 就 是 简单 输出 断 点 的 一 些 值 ， 避 免 必须 进入 独立 的 命令 行 来 做 这 些 事情 。 


这 个 语法 就 是 在 常见 的 断 点 设置 命令 后 面 添加 && 和 对 应 的 Hack 表 达 式 。 假 设 我 们 已 经 在 nphpd 中 加 载 了 下 述 代码 : 


<?hh 


function do_ something expensive (int $level) { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


do_something expensive(10); 


我 们 希望 在 do_something_expensive () 函数 的 调用 上 设置 断 点 ， 然 后 查看 $level 是 什么 值 。 我 们 可 以 像 下 面 这 样 做 : 


hphpd> break do _something expensive() && var dump ($level) 
Breakpoint 1 set upon entering func() && Var_dump ($level) 


hphpd> run 
Breakpoint 1 reached at do _ something expensive() on line 3 of 
/home/oyamauchi /test .php 

2 


3*function do_something expensive(int $level) {} 
4* // http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


你 还 可 以 用 表达 式 配置 一 个 断 点 ， 如 果 该 表达 式 为 真 ， 这 个 断 点 将 会 触发 并 且 和 暂停 执行 。 这 称 之 为 “条 件 断 点 ”。 如 果 想 创建 这 样 一 个 断 点 ， 可 以 使 用 和 有 表达 式 的 断 点 一 样 的 语法 ， 但 是 要 把 语法 中 
的 && 换 成 if。 


在 这 里 ， 我 们 将 继续 在 函数 do_something_expensive () 上 设置 断 点 ， 但 只 有 当 实 参 大 于 9000 的 时 候 才 触发 断 点 。 因 为 在 此 脚本 中 传递 的 实 参 为 10， 所 以 该 断 点 并 不 会 触发 : 


hphpd> break do_something expensive () if $level > 9000 
Breakpoint 1 set upon entering func() if $level > 9000 


hphpd> run 
Program test.php exited normally. 


正如 本 例 中 显示 的 一 样 ， 如 果 你 在 进入 函数 时 设置 一 个 断 点 ， 你 就 可 以 在 断 点 条 件 中 使 用 这 个 函数 的 实 参 了 。 
从 代码 中 设置 断 点 


这 里 还 有 另外 一 个 设置 断 点 的 办 法 ， 就 是 在 PHP 或 者 Hack 代 码 中 调用 一 个 特别 的 函数 hphpd_break () 。 当 由 于 代码 的 物理 布局 导致 很 难 用 行 号 来 设置 断 点 时 ， 这 种 从 代码 内 部 使 用 函数 设置 断 点 的 办 
法 就 变 得 非常 有 用 。 让 我 们 来 看 看 下 面 的 例子 : 


function f(): void { 
echo "one\n"; 
hphpd break () 7 
echo "two\n"; 


} 


当 hphpd_break () 被 执行 的 时 候 ， 若 hphpd 已 经 成 功 附加 上 ， 这 时 表现 出 的 效果 和 在 这 行 设置 了 断 点 一 样 。 执 行将 会 暂停 ,然后 你 将 得 到 调试 器 提示 。 你 可 以 像 其 他 的 断 点 一 样 ， 选 择 从 断 点 步 进 或 
者 恢复 ， 以 进行 下 一 步 操 作 。 


你 还 可 以 对 hphpd_break () 函数 传递 一 个 布尔 型 实 参 ， 当 且 仅 当 这 个 实 参 为 true 的 时 候 ， 这 个 断 点 才 会 工作 。 你 可 以 利用 这 点 把 它 当 作 条 件 断 点 使 用 : 


function f(int Snum) : void { 
hphpd break (Snum < 0) 7 


如 果 这 段 代 码 在 没有 hphpd 的 情况 下 运行 ，hphpd_break () 不 会 做 任何 事情 。 


9.4.2 ”调用 栈 导航 


在 一 个 断 点 上 停 下 后 ， 为 了 定位 你 自己 ， 你 可 以 通过 hphpd 的 where 命 令 输出 一 个 栈 跟 踪 。 (GDB 用 户 将 会 非常 乐于 学 习 这 个 ， 因 为 bt 命令 做 相同 的 事情 。) 这 达到 了 断 点 调试 的 一 个 共同 目的 ， 就 是 
简单 地 找 出 从 哪里 调用 的 相关 代码 。 


我 们 将 使 用 以 下 这 个 文件 : 


<?hh 


function one (string $str) { 
echo $str; 
} 


function two() { 
one ("done\n"); 


} 

function three() { 
two () 7 

} 


three () 7 


我 们 将 在 echo 语 句 上 设置 一 个 断 点 ， 然 后 得 到 一 个 栈 跟踪 : 


hphpd> break test.php:4 
Breakpoint 1 set on line 4 of test.php 


hphpd> 工 

Breakpoint 1 reached at one () on line 4 of /home/oyamauchi/test.php 
3 function one (string $str) { 
4* echo $str; 
5 } 


hphpd> bt 
#0 () 

at /home/oyamauchi/test.php:4 
#1 one ("done\n") 

at /home/oyamauchi/test .php:8 
#2 two () 
at /home/oyamauchi/test.php:12 
#3 three () 
at /home/oyamauchi/test.php:15 


这 个 栈 跟踪 显示 函数 的 实 参 值 ， 你 可 以 用 一 个 配置 选项 关闭 这 个 功能 。 请 查看 表 9-2 中 的 StackArgs ( 见 9.7 节 ) 。 


值得 注意 的 是 ， 在 栈 跟 踪 中 的 每 个 帧 都 有 个 数字 。 最 深 处 的 帧 ( 即 距 离 顶 层 代 码 最 远 的 地 方 )》 编号 为 零 ， 你 距离 顶层 代码 越 近 ， 编 号 越 大 。 你 可 以 利用 编号 来 改变 调试 器 正在 操作 的 帧 。 这 会 影响 @ 和 
= 两 个 评估 命令 (它们 对 当前 帧 进行 操作 ) ， 还 会 影响 观察 命令 variable。 它 也 会 影响 list 命 令 ， 关 于 这 个 命令 ， 我 们 将 9.5 节 进行 详细 解释 。 


这 里 有 个 例子 ， 我 们 将 会 设置 一 个 断 点 ， 然 后 移动 到 一 个 不 同 的 帧 ， 看 看 会 发 生 什么 事情 : 


<?hh 


function do_ something expensive() { 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 


function do something() { 
$level = get level (); 
if ($level > 10) { 
do_something expensive(); 
} 


do_scmething () 7 


// Define get level 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


我 们 将 会 运行 它 ， 然 后 看 看 是 什么 样 的 $level 值 导致 do_something_expensive () 函数 被 调用 。 在 这 个 过 程 中 ， 我 们 将 向 上 移动 到 do_something () 函数 所 在 的 帧 ， 然 后 使 用 variable 命 令 : 


hphpd> break do something _ expensive () 
Breakpoint 1 set upon entering do_something expensive() 


hphpd> run 

Breakpoint 1 reached at do_ something expensive() on line 4 of 

/home/oyamauchi /test .php 
3 function do something expensive() { 
4* // http://wauw.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/OEBPS/Text/... 
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hphpd> where 
#0 do something expensive () 

at /home/oyamauchi/test.php:10 
#1 do something () 

at /home/oyamauchi/test.php:14 


hphpd> frame 1 
#1 do something () 
at /home/oyamauchi/test.php:14 


hphpd> variable 
$level = 9000 


9.4.3 ”代码 导航 


一 旦 你 在 一 个 断 点 暂停 了 ， 这 里 有 很 多 命令 可 以 供 你 使 用 ， 使 执行 继续 。 


这 些 命令 之 中 最 简单 的 就 是 continue， 它 会 简单 地 恢复 正常 执行 。 脚 本 或 者 网 站 请 求 将 会 保持 运行 ， 直 到 它 运 行 完 毕 或 者 碰 到 了 另外 的 断 点 。 (如 果 碰 巧 再 次 执行 断 点 所 在 的 代码 ， 那 么 你 可 能 遇 到 同 
一 个 断 点 。) 设想 下 面 的 代码 在 hphpd 中 被 加 载 : 


<?hh 


function func() { 
echo "Starting func\n"; 
echo "Ending func\n"; 


} 


荆 () 7 


我 们 将 会 在 f () 函数 的 第 二 行 前 设置 断 点 ， 然 后 在 执行 过 程 在 这 里 暂停 后 ， 使 用 continue 命 令 继续 执行 : 


hphpd> break test.php:5 
Breakpoint 1 set on line 5 of test.php 


hphpd> run 
Starting func 
Breakpoint 1 reached at func() on line 5 of /home/oyamauchi/test.php 
4 echo "Starting func\n"; 
5* echo "Leaving func\n"; 
6 } 


hphpd> continue 
Leaving func 
Program test.php exited normally. 


更 有 意思 的 命令 是 step 和 next。 在 碰 到 断 点 之 前 ， 它 们 将 会 按 代码 行 执行 代码 ， 并 且 在 执行 完毕 后 再 次 暂停 。 两 个 命令 的 区 别 在 于 ， 当 被 执行 的 代码 行 包 含 一 个 函数 或 者 方法 的 时 候 ，step 将 会 进入 被 
调用 的 函数 体 ， 并 且 在 执行 第 一 行 代码 之 前 暂停 。next 将 会 直接 跳 到 下 一 行 ， 并 不 会 进入 函数 体 。 换 名 话说， 使 用 next 命 令 的 时 候 ， 调 用 栈 将 不 会 变 得 更 深 。 


这 是 非常 强大 的 调试 代码 的 方式 。 与 在 变量 位 置 添 加 日 志 代码 相 比 ， 你 可 以 设置 断 点 作为 蔡 代 ， 然 后 一 点 一 点 地 执行 ， 在 每 一 步 观察 状态 。 


让 我 们 看 另外 一 个 例子 : 
<?hh 
function inner(): void { 


echo "inner\n"; 


} 


function outer(): void { 
echo "outer\n"; 
inner (); 
echo "done\n™; 


} 


outer () 7 


我 们 在 outer () 函数 上 设置 一 个 断 点 ， 然 后 执行 hext: 


hphpd> break outer () 
Breakpoint 1 set upon entering outer () 
But wont break until function outer has been loaded. 


hphpd> run 
Breakpoint 1 reached at outer() on line 8 of /home/oyamauchi/test.php 
7 function outer(): void { 


8* echo "outer\n"; 
9 inner(); 


hphpd> next 
outer 
Break at outer() on line 9 of /home/oyamauchi/test.php 
8 echo "outer\n"; 
9* jinner(); 
10 echo "done\n"; 


hphpd> next 
inner 
Break at outer() on line 10 of /home/oyamauchi/test.php 
9 inner (); 
10* echo "done\n"; 
11 } 


hphpd> next 
done 
Break at outer() on line 11 of /home/oyamauchi/test.php 
10 echo "done\n"; 
由 
12 


hphpd> next 
Break on line 13 of /home/oyamauchi/test.php 
12 
13*outer (); 
14 (END) 


hphpd> next 
Program test.php exited normally. 


注意 执行 过 程 从 第 九 行 直接 到 了 第 十 行 : 从 对 inner () 函数 的 调用 ， 到 输出 done。 对 inner () 函数 的 调用 被 执行 ， 你 可 以 看 到 inner () 已 经 输出 了 。 但 是 调试 器 在 它们 内 部 并 没有 暂停 。 


现在 让 我 们 用 step 做 相同 的 事情 : 


hphpd> run 
Breakpoint 1 reached at outer () on line 8 of /home/oyamauchi/test.php 
7 function outer () : void { 


8* echo "outer\n"; 
9 inner(); 


hphpd> step 

outer 

Break at outer() on line 9 of /home/oyamauchi/test.php 
8 echo "outer\n"; 
9* jinner(); 
10 echo "done\n"; 

hphpd> step 

Break at inner() on line 4 of /home/oyamauchi/test.php 


3 function inner(): void { 
4* echo "inner\n™; 
51} 


hphpd> step 

inner 

Break at inner() on line 5 of /home/oyamauchi/test.php 
4 echo "inner\n"; 
SA 
6 


hphpd> step 

Break at outer() on line 9 of /home/oyamauchi/test.php 
8 echo "outer\n"; 
9* inner(); 
10 echo "done\n"; 


hphpd> step 

Break at outer() on line 10 of /home/oyamauchi/test.php 
9 inner (); 
10* echo "done\n"; 
11 } 


hphpd> step 

done 

Break at outer() on line 11 of /home/oyamauchi/test.php 
10 echo "done\n"; 
EL 
12 


hphpd> step 

Break on line 13 of /home/oyamauchi/test.php 
12 
13*outer (); 
14 (END) 


hphpd> step 
Program test.php exited normally. 


在 第 九 行 step 后 ， 进 入 第 四 行 : 我 们 在 inner () 函数 内 部 了 。 一 旦 我 们 到 了 inner () 的 结尾 位 置 ， 我 们 将 会 在 第 十 行 返回 outer () (就 是 对 inner () 函数 调用 的 后 一 行 ) 。 


在 这 个 分 类 下 还 有 一 个 其 他 的 命令 out。 它 恢复 执行 直到 你 暂停 的 函数 已 经 退出 ， 这 种 退出 可 能 通过 i 


出 
回 


或 者 抛 出 异常 (或 者 从 调用 栈 的 更 深层 位 置 抛 出 异常 )， 或 者 在 生成 器 的 情况 下 ， 通 过 yield 退 


hphpd> break outer () 

Breakpoint 1 set upon entering outer () 

But wont break until function outer has been loaded. 

hphpd> run 

Breakpoint 1 reached at outer() on line 8 of /home/oyamauchi/test.php 
7 function outer() { 
8* echo "outer\n"; 
9 inner(); 


hphpd> out 

outer 

inner 

done 

Break on line 13 of /home/oyamauchi/test .php 
12 
13*outer (); 
14 (END) 


在 本 案例 中 ， 我 们 在 outer () 函数 的 项 部 暂停 ,然后 执行 out 命 令 。hphpd 会 让 outer () 函数 余下 的 部 分 执行 ， 然 后 在 顶层 代码 位 置 再 次 暂停 ， 仅 在 outer () 函数 调用 返回 之 后 恢复 。 


你 可 以 对 hphpd 进 行 配置 ， 让 step 和 next 每 次 前 进 一 个 表达 式 ， 而 不 是 一 次 一 行 。 见 9.7 节 的 内 容 ， 请 特别 查看 SmallSteps 选 项 。 


名 为 了 方便 你 输入 ， 你 可 以 在 调试 器 提示 中 直接 敲 回 车 键 。 这 样 可 以 重复 continue、next、step 还 有 out 这 四 个 流程 控制 命令 。 换 身 话说 ， 如 果 你 在 命令 行 提示 中 没有 输入 任何 东西 而 直接 敲 回 车 ， 并 且 前 


一 个 命令 是 四 个 流程 控制 命令 中 的 一 个 ， 那 么 前 一 个 命令 将 被 重复 执行 。 


人 A 请 ; ，frame 命 令 并 不 会 改变 next、step 和 out 所 在 操作 的 栈 框架 。 这 就 是 说 ，next 将 会 把 执行 流程 移动 到 任何 地 方 将 被 执行 的 下 一 行 ， 而 不 是 你 正在 查看 的 栈 框架 内 的 下 一 条 将 被 执行 的 代码 行 。 男 
外 两 个 命令 都 是 类 似 的 。 这 和 GDB 的 行为 不 同 ， 所 以 如 果 你 是 一 名 经 验 丰 富 的 GDB 用 户 ， 请 一 定 要 注意 这 点 。 


9.4.4 管理 断 点 


我 们 已 经 学 习 了 如 何 通过 传递 一 个 位 置 到 break 命 令 来 设置 一 个 断 点 。 这 个 break 命 令 还 有 着 很 多 子 指令 ， 你 可 以 使 用 这 些 子 指令 来 对 已 经 存在 的 断 点 进行 管理 。 


首先 ， 让 我 们 学 习 如 何 利用 list 子 指令 来 列 出 所 有 已 经 存在 的 断 点 : 


hphpd> break func () 
Breakpoint 1 set upon entering func () 


hphpd> break test.php:5 
Breakpoint 1 set on line 5 of test.php 


hphpd> break list 
1 ALWAYS upon entering func() 
2 ALWAYS on line 5 of test.php 


第 一 个 区 域 是 断 点 的 编号 ， 这 是 唯一 的 标识 ， 你 可 以 使 用 它 在 其 他 命令 中 引用 对 应 的 断 点 。 当 hphpd 在 一 个 断 点 暂停 的 时 候 ， 它 将 会 输出 这 个 断 点 的 编号 。 断 点 编号 是 单调 递增 的 ， 并 且 不 会 被 重用 。 
所 以 如 果 你 设置 了 两 个 断 点 ， 然 后 删除 了 1 号 断 点 ， 那 么 余下 断 点 的 编号 仍然 是 2。 如 果 你 再 设置 一 个 新 的 断 点 ， 那 么 编号 将 会 是 3。 


| 
上 


第 二 个 区 域 是 断 点 的 状态 。 这 里 有 三 种 可 能 的 状态 : ALWAYS、ONCE、DISABLED。 一 个 ALWAYS 断 点 会 在 每 次 执行 到 达 该 位 置 时 触发 。 一 个 ONCE 断 点 将 会 在 第 一 次 执行 到 该 位 置 时 触发 ， 然 后 这 个 
断 点 的 状态 就 会 变 成 DISABLED。 而 一 个 DISABLED 断 点 不 会 触发 。 


默认 情况 下 ， 你 创建 的 断 点 状态 都 是 ALWAYS。 你 可 以 通过 使 用 once 子 指令 加 上 一 个 位 置 ， 来 创建 一 个 状态 为 ONCE 的 断 点 : 


hphpd> break once func () 
Breakpoint 1 set upon entering func() 


hphpd> break list 
1 ONCE upon entering func () 


这 里 有 三 种 子 指令 用 于 改变 一 个 断 点 的 状态 : enable、disable、toggle。enable 把 一 个 断 点 的 状态 设置 为 ALWAYS， 而 disable 把 它 的 状态 设置 为 DISABLED。toggle 让 一 个 断 点 在 三 个 可 能 的 状态 之 
间 循 环 切换 : 


hphpd> break func () 
Breakpoint 1 set upon entering func() 


hphpd> break toggle 1 
Breakpoint 1's state is changed to ONCE. 


hphpd> break toggle 1 
Breakpoint 1's state is changed to DISABLED. 


hphpd> break toggle 1 
Breakpoint 1's state is changed to ALWAYS. 


hphpd> break disable 1 
Breakpoint 1's state is changed to DISABLED. 


hphpd> break enable 1 
Breakpoint 1's state is changed to ALWAYS. 


可 以 使 用 clear 子 指令 加 上 断 点 编号 来 完全 删除 一 个 断 点 : 


hphpd> break clear 1 
Breakpoint 1 cleared upon entering func () 


对 于 clear、disable、enable 和 toggle 四 个 子 指令 ， 你 可 以 在 断 点 编号 的 位 置 使 用 all， 这 样 对 应 的 操作 将 会 应 用 到 所 有 的 断 点 : 


hphpd> break clear all 
All breakpoints are cleared. 


你 也 可 以 在 上 述 子 指令 后 不 传递 任何 实 参 。 那 么 所 做 的 操作 将 会 对 碰 到 的 最 新 的 断 点 生效 : 


hphpd> break func () 
Breakpoint 1 set upon entering func () 


hphpd> = func () 
Breakpoint 1 reached at func() on line 3 of /home/oyamauchi/test.php 


hphpd> break clear 
Breakpoint 1 is cleared at func () 


中 为 清晰 起 见 ， 我 们 将 会 在 本 书 中 使 用 完整 的 命令 ， 但 是 请 记 住 ， 你 可 以 把 这 些 命令 简写 为 其 首 字母 形式 。 你 可 以 输入 b testphp:5 来 代替 break test.php:5， 效 果 完 全 一 致 。 
B] “PSP” 人 代表“ 提交 发 送 进程 (post-send processing) ”， 在 HHVM 中 是 shutdown 函 数 被 初始 调用 的 地 方 。 
DB] 例如 ， 在 URI https://www.example.com/something/somethingphp?key=val 中 ， 这 个 路 径 部 分 是 /something/somethingphp。 


9.5 ”查看 代码 和 文档 


当 你 的 代码 正在 执行 ， (就 是 说 ， 你 在 一 个 断 点 暂停 了 ， 或 者 在 断 点 暂停 后 的 步 进 过 程 中 ，) 你 可 以 使 用 list 命 令 来 展示 当前 被 执行 代码 的 周边 。 如 果 你 正在 使 用 frame 命 令 查看 一 个 不 同 的 栈 框架 ，list 
将 会 展示 出 本 frame 中 相关 调用 点 的 周边 代码 : 


hphpd> break func () 
Breakpoint 1 set upon entering func() 


hphpd> 工 

Breakpoint 1 reached at func() on line 7 of /home/oyamauchi/test.php 
6 function func(): void { 
7* echo "Just kigdding, it's pretty boring"; 
8 } 


hphpd> list 
list 
1 <?hh 
2 
Es 
4 * This is a very interesting function 
By 
6 function func(): void 1{ 
7* echo "Just kidding, it's pretty boring"; 


在 运行 list 命 令 之 后 ， 如 果 你 在 接 下 来 的 调试 器 提示 行 中 没有 输入 任何 字符 而 直接 敲 回 车 的 话 ， 那 么 调试 器 将 会 显示 接 下 来 的 几 行 代码 。 你 可 以 一 直 这 样 做 ， 直 到 该 文件 的 尾部 。 


为 了 指明 你 要 查看 的 代码 ， 这 里 有 大 量 的 实 参 可 以 用 于 传递 给 list。 表 9-1 将 会 对 它们 具体 展示 。 


表 9-1: list 命 令 的 实 参 


和 全 人、 
RD x 


展示 


by 
yl 
es 
ez, 
册 


可 
这 
团 


list 
list 
list 
list 
某 个 文件 的 行 范 围 。 1ist 


List 
list 
list 
命名 实体 list 
list 
list 


34-45 

34- 

-45 

34 
test.php:34-35 


test.php:34- 
test.php:-45 
test.php:34 
func 
ClassName 


ClassName: :methodName 


当前 文件 的 第 34 行 到 45 行 

第 34 行 到 当前 文件 的 结尾 

当前 文件 开始 位 置 到 第 45 行 

当前 文件 第 34 行 的 周边 行 

和 上 述 内 容 一 致 ， 但 不 是 当前 文件 ， 而 是 
在 testphp 中 。 路 径 与 依附 的 沙 盒 根 路 径 
相关 ， 如 果 没 有 的 话 ， 则 相对 于 当前 的 工 
作 目 录 . 


函数 func( ) 的 源码 
ClassName 类 (接口 或 者 trait) 的 源码 
ClassName 类 中 methodName 方法 的 源码 


你 可 以 使 用 info 命 令 查找 文档 注释 和 签名 。 把 一 个 命名 实体 [1 的 名 称 作为 实 参 传递 到 这 个 命令 中 。 如 果 想 要 查看 一 个 方法 ， 请 使 用 ClassName: : methodName 符 号 。 


假设 test.php 文 件 拥 有 如 下 内 容 : 


<?hh 
太太 
* A class 


Class C { 


J 
* 一 个 类 内 部 的 方法 
Public function method(C S$obj) : void { 
下 


/x** 


* A function 
六 


function f(int $x): void { 


我 们 可 以 使 用 下 面 的 方法 来 获得 该 文件 中 定义 的 实体 的 相关 信息 : 


$ hhvm -m debug test.php 
hphpd> info C 


// defined on line 6 to 13 of /home/oyamauchi/Vtest.Php 
Ar 


* A class 
class C { 


// methods 
[doc] public function method(C $obj) 


hphpd> info C::method 


// defined on line 11 to 12 of /home/oyamauchi/test.php 


/x# 


* A method inside the class 
A 
public function C::method(C $0obj); 


hphpd> info f 


// defined on line 18 to 19 of /home/oyamauchi/test .Php 
AN 


* A function 
六 


function f(HHNint $x); 


这 对 内 置 的 函数 、 类 和 接口 仍然 有 效 : 


hphpd> info strtoupper 
人 


* Returns string with all alphabetic characters converted to uppercase. Note 
* that 'alphabetic' is determined by the current locale. For instance, in the 
* default "C" locale characters such as umlaut-a will not be converted. 


* Qparam string $str - The input string. 
太 


* Qreturn string - Returns the uppercased string. 


和 
本 
function strtoupper (HH\string $str); 


中 一 个 命名 实体 是 一 个 函数 、 类 、 接 口 、 常 量 、trait、 枚 举 或 者 类 型 别名 。 


9.6 


浏 


hphpd 拥 有 用 于 录制 和 重播 命令 序列 的 特性 。 这 些 序列 称 之 为 宏 (macros) 。 它 们 被 自动 保存 到 你 的 home 目 录 一 个 名 为 .hphpd ini 的 文件 中 。 所 以 它们 能 够 在 hphpd 会 话 中 持久 。 (这 个 文件 同时 保 
存 着 hphpd 的 配置 选项 ， 具 体 可 以 查看 9.7 节 的 内 容 。) 


使 用 宏 的 命令 是 &。 为 了 开始 录制 一 个 宏 ， 使 用 它 的 子 指令 start， 然 后 输入 你 想 要 录制 的 命令 。 结 束 的 时 候 ， 使 用 & 和 子 指令 end : 


hphpd> & start 


hphpd> Q@echo "hi" 
hi 


hphpd> & end 


现在 ， 你 可 以 使 用 子 指令 replay 重 播 这 个 录制 好 的 指令 序列 了 。 在 这 个 例子 中 ， 我 们 并 没有 真实 输入 @echo 语 句 。 它 是 被 hphpd 自 动 执行 的 ， 当 它 结束 后 ， 我 们 将 回 到 调试 器 提示 : 


hphpd> & replay 


hphpd> Q@echo "hi" 
hi 


hphpd> 


当 开 始 录制 一 个 宏 的 时 候 ， 你 还 可 以 给 宏 命 名 。 方 法 就 是 给 start 子 指令 传递 一 个 实 参 。 如 果 你 并 没有 给 它 命名 ， 它 将 会 使 用 名 字 default。 这 就 意味 着 如 果 你 录制 一 个 没有 命名 的 宏 ， 然 后 再 录制 另外 一 
个 没命 名 的 宏 ， 那 么 第 一 个 宏 将 会 被 覆盖 : 


hphpd> & start some name 


hphpd> echo "some named macro" 
some named macro 


hphpd> & end 


你 还 可 以 对 relpay 子 指令 传递 一 个 名 字 来 重 放 命 名 的 宏 。 默 认 情 况 下 ， 它 会 对 名 为 default 的 宏 进行 重播 : 


hphpd> & replay some name 
hphpd> Qecho "some named macro" 
some named macro 


你 可 以 使 用 list 子 指令 查看 所 有 存在 的 宏 : 


hphpd> & list 
1 default 


> Qecho "some named macro" 


这 个 输出 将 会 显示 编号 、 名 称 及 每 个 宏 的 内 容 。 


最 后 ， 你 可 以 使 用 子 指令 clear 来 删除 一 个 宏 ， 但 是 注意 使 用 宏 编号 进行 删除 ， 而 不 是 宏 名 字 : 


hphpd> & clear 1 
Are you sure you want to delete the macro? [y/N] y 


hphpd> & list 
1 some name 
> Qecho "some named macro\n" 


注意 和 断 点 编号 不 一 样 的 是 ， 宏 编号 并 不 是 永久 和 一 个 宏 联 系 在 一 起 的 。 如 果 我 们 删除 了 1 号 宏 ， 那么 原来 的 2 号 宏 将 会 上 升 为 新 的 1 号 。 这 就 是 宏 实现 时 候 的 异常 现象 。 如 果 你 觉得 它 奇 怪 、 很 不 正常 
的 话 ， 就 对 了 。 


宏 名 称 startup 是 被 特殊 对 待 的 。 当 hphpd 启 动 和 加 载 设置 的 时 候 ， 它 将 会 查找 一 个 叫做 startup 的 宏 。 然 后 如 果 它 找到 了 一 个 ， 它 将 会 在 从 调试 器 提示 拿 到 任何 输入 项 目 之 前 ， 立 即 重播 这 个 startup 


旋 


当 你 在 调试 的 时 候 ， 可 能 发 现 有 一 些 工具 函数 或 类 的 集合 是 你 调试 时 经 常 使 用 的 。 你 可 以 在 startup 宏 里 面包 含 这 些 文件 ， 那 么 你 每 次 启动 hphpd 时 它们 都 会 有 效 。 


9.7 配置 hphpd 


加 
虽 


我 们 还 没有 涉及 的 最 后 一 个 主要 命令 是 set。 它 允许 你 改变 一 些 配 置 选项 来 控制 hphpd 的 行为 。 大 多 数 可 配置 的 选项 控制 hphpd 输 出 方面 的 内 容 。 表 9-2 显 示 了 所 有 的 可 用 ; 


表 9-2: hphpd 配 置 


名 称 简写 可 能 的 值 默认 值 
BypassAccessCheck bac on, off off 
LogFile 1f off 或 者 一 个 文件 路 径 。 off 


PrintLevel pl 整 型 5 


表 9-2: hphpd 配 置 ( 续 ) 


名 称 简写 可 能 的 值 默认 值 
ShortpTrintCharCount cc 整 型 200 


SmallSteps SS on, off off 


StackArgs Sa on, off on 
MaxCodeLines mcl 整 型 -1 


如 果 你 不 使 用 任何 实 参 来 运行 set 命令 (这 就 是 说 ， 只 输入 set， 而 没有 其 他 任何 东西 ) ，hphpd 将 会 显示 所 有 选项 以 及 它们 的 当前 值 。 为 了 设置 一 个 选项 ， 请 传递 两 个 实 参 到 set 命 令 。 首 先是 配置 选项 
的 名 字 或 者 该 配置 选项 的 简写 。 其 次 是 将 要 设置 的 值 (例如 set bac on 或 者 set LogFile off) 。 让 我 们 近 距 离 对 这 些 选项 进行 查看 : 


3 


BypassAccessCheck 


开启 这 个 选项 后 ， 对 于 从 调试 器 提示 中 调用 的 代码 ，hphpd 将 会 忽略 代码 中 的 protected 和 private 访 问 修饰 符 。 而 运行 于 网 络 请 求 中 的 代码 将 不 会 受 此 选项 影响 。 


LogFile 


如 果 这 个 选项 值 不 是 off 而 是 其 他 值 的 话 ， 它 将 会 解释 为 一 个 文件 路 径 ， 并 且 hphpd 将 会 把 它 所 有 的 输出 项 目 复制 到 这 个 文件 中 。 它 并 不 会 捕获 你 的 输入 项 目 。 


了 PrintLevel 


这 个 可 以 控制 print 命 令 可 以 输出 的 对 象 和 数组 嵌 套 的 最 大 数量 。 如 果 是 零 或 者 负数 ， 这 里 不 会 有 最 大 数 限制 ， 对 象 和 数组 将 会 完整 输出 。 但 是 如 果 这 里 有 递归 谋 套 ， 当 递归 开始 的 时 人 息 ， 输 出 将 会 被 截 
断 忽略 这 个 选项 的 配置 值 。 


ShortPrintCharCount 


这 个 配置 选项 可 以 控制 在 单一 的 = 命令 中 将 被 输出 的 字符 的 最 大 数量 。 如 果 是 零 或 者 负数 ， 这 里 不 会 有 最 大 数量 。 如 果 一 个 = 命令 产生 比 最 大 数 限制 更 多 的 字符 ，hphpd 将 会 询问 你 是 否 想 查 看 剩余 的 内 
容 ， 你 可 以 像 其 他 的 交互 式 命令 行 一 样 ， 输 入 y 或 者 n 来 回答 这 个 问题 。 


SmallSteps 


这 个 配置 选项 可 以 控制 step 和 next 命 令 的 行为 。 如 果 它 被 设置 为 off (默认 值 ) ， 这 些 命令 将 会 把 你 带 向 下 一 行 代码 的 大 概 位 置 。 如 果 设置 为 on， 它 将 会 把 你 带 向 要 执行 的 下 一 个 表达 式 的 大 概 位 置 。 


StackArgs 


如 果 这 个 选项 保持 开启 ，where 命 令 输出 的 回 朔 跟踪 将 会 显示 回 闭 中 传递 到 函数 中 的 实 参 。 


回 


MaxCodeLines 


当 hphpd 在 一 个 断 点 暂停 后 ， 或 者 在 step 或 者 next 命 令 之 后 ， 它 将 会 输出 暂停 位 置 的 源码 ， 并 且 保 持 相关 部 分 高 亮 。 在 一 些 情 况 中 ， 这 可 能 是 跨越 了 很 多 行 的 大 量 代码 。 例 如 一 个 大 的 数组 表达 式 ， 每 
个 成 员 都 在 它 自 己 的 行 上 。 在 这 种 情况 下 ， 这 个 选项 可 以 用 来 限制 将 要 输出 的 行 数量 ， 以 免 瘫 疼 你 的 终端 。 


如 果 这 个 选项 设置 为 0， 那 么 当 一 个 断 点 暂停 时 ， 将 不 会 有 代码 输出 。 如 果 是 负数 (默认 值 ) 的 话 ， 这 里 将 不 会 有 任何 限制 。 


hphpd 把 这 些 设置 保存 到 home 目 录 下 面 叫做 .hphpd.ini 的 文件 中 。 并 且 在 你 下 一 次 启动 hphpd 的 时 候 ， 将 会 加 载 这 些 保存 好 的 设置 选项 。 你 可 以 手工 编辑 这 个 文件 ， 以 改变 你 保存 的 设置 选项 。 


第 10 章 Hack 工具 


一 门 编程 语言 的 特性 只 是 使 它 走向 完美 道路 上 的 一 部 分 。 如 果 要 表现 得 更 加 强大 ， 语 言 需要 有 一 个 完善 的 周边 工具 生态 系统 : 编辑 器 及 IDE 支 持 ， 调 试 器 、 静 态 分 析 工 具 和 lint 工 具 等 。Hack 的 类 型 检查 
器 构建 在 强大 的 静态 分 析 平台 上 ， 这 个 平台 可 以 支持 很 多 这 种 用 途 。 


标准 的 HHVMVHack 安 装 中 会 附带 很 多 有 用 的 代码 检查 工具 ， 包 括 从 PHP 迁 移 到 Hack 的 工具 以 及 把 Hack 转 换 为 PHP 的 工具 。 本 : 讲述 这 些 工 具 。 


10.1 ”检查 代码 库 


Hack 类 型 检查 器 的 核心 基础 架构 是 一 个 服务 端 ， 用 于 记录 关于 代码 库 的 一 系列 事实 。 可 以 使 用 hh_client 基 于 对 上 述 一 系列 事实 的 查询 来 检查 类 型 错误 。 关 于 hh_client 查 询 数据 ， 本 节 将 对 其 他 可 用 的 
选项 进行 阐述 : 


--search 


这 同时 会 对 搜索 内 置 符号 系统 进行 查询 。 


清 
册 


使 用 这 个 标志 位 可 以 执行 一 个 对 给 定 符号 名 称 的 模糊 查询 。 在 该 标志 位 后 传递 一 个 用 于 查询 的 字符 串 作 为 实 参 。 请 注 


$ hh client --search wrap 
File “/home/oyamauchi/hack/test.php", line 58, characters 7-13: Wrapper, 
Class 


这 个 查询 是 非常 灵敏 的 。 类 型 检查 器 的 服务 器 端 对 代码 库 进行 索引 ， 并 不 需要 读 取 任何 源 文 件 就 能 够 执行 该 搜索 功能 。 


这 里 有 很 多 相关 的 标志 位 ， 用 于 限制 将 会 返回 的 符号 种 类 : --search-class、--search-function、--search-constant 和 --search-typedef (这 个 搜索 类 型 别名 ) 。 每 个 使 用 方法 都 和 --search 参 数 的 使 
方法 一 致 ， 并 且 返 回 的 输出 也 是 统一 的 格式 。 


--type-at-pos 


使 用 这 个 标志 位 可 以 询问 类 型 检查 器 表达 式 应 该 是 什么 类 型 的 。 在 命令 行 中 依次 传递 用 冒号 分 隔 的 文件 名 称 、 行 号 及 列 号 ， 就 可 以 对 这 个 位 置 的 表达 式 进行 观察 : 


$ cat test.php 
<?hh // strict 


function reversed digits (int $x): string { 
return strrev((string) $x); 


} 


function main(): void { 
$f = fun('reversed digits'); 
echo $f(123); 


} 

# Get type of $x within reversed digits 
$ hh client -~-type-at-pos test.php:4:25 
int 


# Get type of result of string cast 
$ hh client -~-type-at-pos test.php:4:17 
string 


# Get type of $f in main() 
$ hh client --type-at-pos test.php:8:3 
(function (int $x): string) 


给 出 的 类 型 结果 是 针对 给 定位 置 最 核心 的 表达 式 的 。 例 如 ， 如 果 你 对 表达 式 $a+$b 中 的 字符 a 进行 查询 ， 那 么 得 出 的 结果 将 会 是 $a 的 类 型 ， 而 不 是 $a+$b。 在 这 种 情况 下 ， 如 果 你 想得到 | 整个 表达 式 的 
类 型 结果 ， 那 么 请 对 字符 + 进行 查询 。 


请 注意 ，--type-at-pos 的 输出 结果 可 能 不 是 合法 的 类 型 标注 ， 它 纯粹 用 于 信息 传递 目的 。 最 明显 的 是 ， 对 于 特殊 的 没有 标注 类 型 的 值 (参见 1.4.2 节 的 相关 内 容 ) ，--type-at-pos 将 会 输出 一 个 下 划 线 


--find-refs 和 --find-class-refs 


回 


使 用 --find-refs 可 以 查询 对 给 定 函 数 或 者 方法 的 引用 。 使 用 --find-class-refs 可 以 查询 对 给 定 类 的 引用 。 在 该 标志 位 后 面 传递 一 个 类 、 函 数 或 方法 的 名 字 作为 实 参 : 


$ cat test.php 
<?hh // strict 


class C {} 
class D extends C {} 


function main(): void { 
$c = new C(); 


} 


$ hh client --find-class-refs C 

File "/home/oyamauchi/hack/test.php", line 8, characters 12-12: 
C::__construct 

File "“/home/oyamauchi/hack/test.php", line 5, characters 17-17: C 

2 total results 


--inhetitance-ancestorfs 和 --inhetitance-children 


使 用 这 些 标 志 位 可 以 分 别 获 取 给 定 类 的 祖先 类 及 派生 类 。--inheritance-children 实 际 上 会 输出 所 有 的 派生 类 ， 而 不 仅仅 是 直接 的 子 类 : 


$ cat test.php 
&#x3c; ?hh // strict 


class GrandparentClass {} 

Class ParentClass extends GrandparentClass {} 
class Childone extends ParentClass {} 

class ChildTwo extends ParentClass {} 


$ hh client --inheritance-ancestors Childone 

File “/home/oyamauchi/hack/test.php", line 7, characters 7-14: Childone 
inherited from File "/home/oyamauchi/hack/test.php", line 5, 
characters 
7-17; ParentClass 

File "/home/oyamauchi/hack/test.php", line 7, characters 7-14: Childone 
inherited from File "/home/oyamauchi/hack/test.php", line 3, 
characters 
7-22: GrandparentClass 


$ hh client --inheritance-children 
GrandparentClass 
File "/home/oyamauchi/hack/test.php", line 3, characters 7-22: 
GrandparentClass 
inherited by File "/home/oyamauchi/hack/test.php", line 9, 
characters 7-14: 
ChildTwo 
File "/home/oyamauchi/hack/test.php", line 3, characters 7-22: 
GrandparentClass 
inherited by File "/home/oyamauchi/hack/test.php", line 7, 
Characters 7-14: 


Childone 
File "“/home/oyamauchi/hack/test.php", line 3, characters 7-22: 
GrandparentClass 
inherited by File "/home/oyamauchi/hack/test.php", line 5, 
characters 7-17: 
ParentClass 


脚本 支持 


类 型 检查 器 客户 端 可 以 把 它 的 命令 结果 输出 为 JSON 格 式 ， 这 样 方便 你 在 其 


他 的 工具 


hh_client 命 令 行 后 即 可 : 


(编辑 器 、IDE、 代 码 监听 及 反射 工具 等 ) 里 面 进行 集 成 。 仅 仅 在 其 他 的 实 参 前 


H 


添加 一 个 标志 位 --json 到 任何 


$ cat test.php 
<?hh // strict 
function main(): void { 
$var = 1 + "3"; 


} 


$ hh client --json 
{ 
"passed": false, 
"errors": [ 
{ 


"message": [ 


"descr": "Typing error", 
"path": "/home/oyamauchi/hack/test .php", 
"line": 4, 
atart ts Ta 
end": 16, 
code": 4110 
kb 
{ 
"gescr": "This is a num (int/float) because this is used in an 


arithmetic operation", 
"path": "/home/oyamauchi/hack/test.php", 
"line" 


: "It is incompatible with a string", 
: "/home/oyamauchi/hack/test.Php"， 


] 
} 
] 


} 


"Version": "0939324e1252832cf6f65c51ff2cb811dad307ba Mar 8 2015 23:44:12" 


这 里 展示 的 输出 为 了 易 读 性 而 进行 了 格式 化 。hh_client 的 JSON 输 出 没有 任何 多 余 的 空白 


10.2 迁移 PHP 代 码 到 Hack 


Hack 的 创造 者 比 大 家 更 懂得 对 一 个 大 型 的 代码 库 做 代码 转换 是 多 么 


困 


难 。 当 第 一 次 构想 Hack 的 时 候 ，Facebook 有 基于 


当 大 多 数 的 代码 
变化 很 快 ， 所 以 使 


Hack 进 行 编写 的 时 候 ， 使 用 Hack 的 益处 开始 
手工 办 法 进行 迁移 显然 是 非常 困难 的 。 


在 这 种 情况 下 ， 几 种 


于 把 代码 从 PHP 到 Hack 


动迁 移 的 工 


展现 。 对 于 Facebook 来 说 ， 这 就 意味 着 使 


字符 。 


某 种 方式 把 大 篇 幅 的 代码 


软件 应 运 而 生 。 标 准 的 HHVM/Hack 安 装 中 包含 了 这 些 软件 。 


FFPHP 的 数 以 干 万 行 的 代码 库 ， 这 是 几 百 名 工程 师 共 同 劳动 的 结晶 。 


动 进行 迁移 是 Hack 赢 得 推广 的 必 备 条 件 。 代 码 库 非常 庞大 而 且 


10.2.1 Hackificator 

转化 PHP 代 码 库 到 Hack， 首 先 选取 的 工具 就 是 Hackificator。 它 可 以 提供 一 个 初始 的 “ 笔 刷 转换 (broad-strokes conversion) ”。 它 会 对 目录 中 的 PHP 文 件 进行 扫描 ， 然 后 对 这 种 文件 执行 如 下 两 
步 : 

1. 它 会 做 一 些 简单 的 机 械 性 变化 ， 以 避免 一 些 Hack 错 误 。 例 如 ， 默 认 值 为 null 的 类 型 提示 的 形 参 ， 将 改变 类 型 提示 为 nullable。 这 就 是 说 ， 在 PHP 中 合法 的 function f (int$x=null) 在 Hack 中 就 是 类 型 
错误 ， 需 要 变 为 function f (? int$x=null) 。 

2. 它 把 文件 开始 标记 <? php 变 成 <? hh， 使 用 不 引起 任何 类 型 检查 器 错误 的 最 严格 的 模式 ， 而 这 种 模式 通常 会 是 局 部 或 者 耦合 模式 。 

除 此 之 外 ，Hackificator 不 会 做 其 他 的 事情 。 它 致力 于 最 低 限度 地 对 Hack 检 查 器 暴露 代码 。 

在 执行 Hackificator 之 前 ， 已 经 是 Hack 的 文件 代码 不 能 有 任何 的 类 型 检查 器 错误 。 这 就 是 说 ， 运 行 hh_client 的 时 候 不 能 有 任何 错误 输出 ! 如 果 这 里 有 错误 输出 ，Hackificator 会 拒绝 执行 。 

自 上 而 下 或 者 自 下 而 上 迁移 

需要 特别 声明 的 一 点 是 ，Hackificator 一 次 处 理 的 文件 顺序 是 不 规则 的 。 转 换 完毕 的 文件 顺序 可 能 会 导致 最 终 的 执行 结果 不 同 。 

为 了 说 明 这 一 点 ， 我 们 看 一 个 常见 情况 的 简化 版 本 。 在 一 个 PHP 文 件 中 ,我 们 有 一 个 抽象 超 类 。 很 多 具体 的 子 类 实现 分 布 在 其 他 的 PHP 文 件 中 ， 这 些 子 类 大 概 有 几 十 个 甚至 上 百 个 。 在 这 个 例子 中 ,我 
们 将 仅仅 看 到 一 个 。 

假设 我 们 已 经 拥有 了 文件 Workltem.php: 
_ 人 


abstract class WorkItem { 
abstract public function doWork(); 
} 


还 有 文件 AckermannWorkltem.php: 


<?php 


Class AckermannWorkItem extends WorkItem { 
public function domork () { 
Sthis->running = true; 
// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 
} 
} 


首先 需要 注意 的 一 点 是 ， 如 果 我 们 转换 所 有 文件 到 局 部 模式 的 Hack 文 件 ， 这 里 会 有 “具体 子 类 正在 使 用 一 个 未 声明 的 属性 ”的 错误 。 因 此 ， 我 们 最 佳 的 做 法 是 保持 一 个 文件 为 局 部 模式 ， 另 外 一 个 文件 
为 耦合 模式 或 者 保留 为 PHP。 


如 果 hackificator 首 先 处 理 Workltem.php， 它 将 会 把 这 个 文件 设置 为 局 部 模式 。 因 为 子 类 仍然 在 PHP 文 件 中 ， 它 们 对 类 型 检查 器 来 说 是 不 可 见 的 。 而 Workltem.php 本 身 在 局 部 模式 下 没有 错误 [1。 然 
后 ， 当 它 处 理 AckermannWorkltem.php 文 件 的 时 候 ， 它 只 能 把 这 个 文件 放 到 耦合 模式 下 。 因 为 超 类 是 在 Hack 中 ， 它 能 够 分 析出 整个 层次 ， 并 且 检 测 出 running 属 性 没 被 声明 ， 这 在 其 他 非 耦 合 模式 下 就 会 
产生 一 个 错误 。 


如 果 hackificator 先 处 理 AckermannWeorkltem.php 文 件 ， 它 将 会 把 这 个 文件 置 于 局 部 模式 。 它 的 超 类 仍然 在 PHP 文 件 中 ， 所 以 对 类 型 检查 器 是 不 可 见 的 。 类 型 检查 器 会 假设 running 属 性 在 其 超 类 中 声 
明了 ， 所 以 这 里 并 不 会 产生 什么 错误 。 然 后 ， 当 它 试图 转换 Workltem.php 文 件 到 Hack 的 时 候 ， 一 个 未 声明 的 属性 错误 就 会 在 AckermannWeorkltem.php 中 弹出 ， 因 为 它 的 超 类 现在 对 类 型 检查 器 是 可 见 的 
了 。 在 对 AckermannWeorkltem.php 处 理 完 毕 的 前 提 下 ，hackificator 只 能 把 Workltem.php 重 新 转换 回 PHP， 而 不 是 再 次 回 到 AckermannWorkltem.php 把 它 转换 为 耦合 模式 以 消除 错误 输出 。 


第 一 种 模式 下 ， 首 先 迁 移 的 是 超 类 。 这 是 一 种 自 上 而 下 的 迁移 到 Hack 的 模式 。 其 好 处 就 是 ， 任 何 新 的 子 类 都 可 以 从 Hack 开 始 ， 然 后 通过 超 类 的 类 型 检查 器 知识 获得 益处 ， 甚 至 当 其 他 子 类 还 没有 开始 
迁移 的 时 候 本 子 类 也 可 以 获得 益处 。 对 稳定 的 层次 一 步 一 步 开 展 全 面 的 类 型 检查 ， 代 码 的 迁移 进度 也 从 0% 到 100% 以 线性 递增 。 


第 二 种 模式 下 ， 在 它 所 有 的 子 类 都 在 Hack 中 之 后 再 迁移 超 类 。 这 是 一 种 自 下 而 上 的 迁移 。 这 种 情况 的 好 处 就 是 ， 它 可 以 更 快 转化 更 多 的 代码 到 Hack 中 。 然 而 类 型 检查 器 在 子 类 上 有 功能 局 限 ， 因 为 类 
型 检查 器 对 子 类 的 超 类 知识 一 无 所 知 。 大 多 数 的 层次 被 检查 ， 都 带 着 这 种 迁移 开始 时 的 局 限 ， 而 这 种 有 局 限 的 检查 将 一 直 持续 到 几乎 迁移 过 程 结 束 。 


正 是 基于 Hackificator 的 这 种 工作 方式 ， 它 更 有 可 能 产生 一 个 自 下 而 上 的 转化 ， 仅 仅 因 为 从 数量 上 来 说 ， 子 类 可 以 有 很 多 个 ， 而 超 类 只 有 一 个 。 那 么 最 有 可 能 的 情况 就 是 Hackificator 的 转化 从 一 个 子 类 
开始 。 如 果 你 想 确 保 这 是 一 个 自 上 而 下 的 转化 ， 请 在 执行 Hackificator 之 前 手工 对 超 类 进行 转化 。 


没有 哪 种 模式 相对 于 另外 一 种 模式 更 好 ， 你 可 以 在 同一 个 代码 库 内 的 不 同类 结构 上 同时 使 用 这 两 种 模式 。 我 们 这 里 对 它们 进行 讨论 以 便 你 知晓 使 用 Hackificator 的 预期 ， 并 帮助 你 做 出 深思 熟 虑 的 选 
择 。 


Facebook 的 代码 迁移 到 Hack 


当 Facebook 把 代码 库 迁 移 到 Hack 的 时 候 ， 它 是 自 下 而 上 完成 的 。 它 并 没有 走 “ 一 些 总 体 规划 的 一 部 分 ”这 样 的 道路 ， 它 是 一 个 突 生 现象 。 关 于 自 上 而 下 还 是 自 下 而 上 的 想法 仅仅 是 这 次 迁移 经 验 的 产 
物 ， 而 不 是 开始 就 有 这 种 结论 的 。 


Facebook 自 下 而 上 的 迁移 碰 到 了 很 多 陷阱 。 这 个 代码 库 有 一 个 类 似 WorkItem 的 核心 类 ， 这 个 核心 类 拥有 超过 25000 个 派生 类 。 甚 至 当 大 多 数 的 派生 类 被 成 功 转 化 后 ， 把 整个 层次 上 的 超 类 放 到 Hack 中 仍然 
是 个 非常 重大 的 任务 ， 因 为 最 终 当 整个 层次 结构 可 以 全 面 检查 后 ， 大 量 的 类 型 检查 器 错误 暴露 出 来 。 


为 了 绕 过 这 个 问题 ， 我 们 最 终 选择 了 PHP 文 件 中 叫做 CrippleHackTypechecking 的 trait， 当 WorkItem 本 身 被 放 进 Hack 后 ， 我 们 在 开始 展示 错误 的 WotkItem 派 生 类 中 使 用 这 个 trait。 这 个 trait 本 身 没 有 任何 功 
能 ， 它 存在 的 目的 就 是 在 一 些 派生 类 中 ， 有 选择 地 妨碍 类 型 检查 器 ， 以 便 进一步 调试 。 


到 这 里 为 止 ， 剩余 的 迁移 工作 基本 上 只 是 一 秒 钟 的 事情 了 ， 从 上 到 下 依次 完成 。 逐 步 修 复 派生 类 ， 并 且 从 它们 中 移 除 CrippleHackTypechecking。 
Fackbook 从 来 没有 做 过 一 个 大 型 、 全 面 、 自 上 而 下 的 PHP 到 Hack 的 迁移 工作 ， 因 为 尚 不 清楚 这 种 方法 是 否 存在 某 些 未 知 的 缺陷 。 


更 新 类 型 检查 器 模式 


Hackificator 还 有 其 他 类 型 的 转化 功能 ， 这 种 功能 可 以 检查 Hack 文 件 (并 不 是 PHP 文 件 ) ， 并 升级 它们 到 不 引起 类 型 检查 器 错误 的 最 严格 模式 。 可 以 通过 在 命令 行 里 面 添 加 标志 位 -upgrade ( 单 连 字 


符 ) 来 激活 这 个 功能 。 


由 于 Hackificator 的 默认 行为 几乎 不 会 产生 一 个 严格 模式 的 文件 ， 所 以 这 项 功能 常常 是 有 用 的 。 这 是 因为 在 严格 模式 下 ， 要 求 所 有 的 返回 类 型 应 该 是 被 标注 的 ， 但 Hack 的 返回 类 型 标注 语法 在 PHP 中 是 
非法 的 (在 所 有 的 5.X 版 本 和 更 早 的 版 本 中 ) 。 


如 果 把 hackificator-upgrade 和 hh_server--convert 联 合 使 用 ， 那 么 将 非常 有 用 。 我 们 将 在 下 一 节 中 做 进一步 的 描述 。 那 个 工具 会 通过 添加 类 型 标注 ,使 一 个 局 部 模式 文件 到 一 个 全 新 的 状态 ， 能 够 干 
净利 落地 升级 到 局 部 模式 。 


10.2.2 ”推断 和 添加 类 型 标注 


添加 类 型 标注 需要 做 更 多 的 手工 工作 ， 所 以 非常 环 手 。 类 型 检查 器 提供 了 一 个 模式 ， 在 这 种 模式 下 它 会 尝试 推断 一 个 未 标注 类 型 的 值 。 通 过 对 已 经 标注 和 已 知 的 类 型 进行 逆向 作业 ， 标 注 代码 中 推断 出 
的 类 型 。 


需要 重点 指出 的 是 ， 这 个 过 程 并 非 完 美 无 缺 。 推 断 出 的 类 型 标注 可 以 放心 使 用 ， 并 不 会 引起 类 型 检查 器 错误 ， 但 它们 可 能 在 运行 土 环境 中 是 错误 的 。 正 因为 这 样 ， 所 有 添加 的 类 型 标注 都 是 软 性 的 ， 这 
样 在 运行 环境 中 它们 将 引起 警告 而 不 是 致命 错误 。 


为 了 处 理由 于 这 种 软 性 类 型 提示 引起 的 结果 扩大 化 问题 ， 这 里 有 两 个 其 他 的 工具 用 于 对 这 种 情况 补充 : 一 个 读 取 日 志文 件 ， 然 后 移 除 所 有 在 日 志 中 引发 警告 的 软 性 类 型 提示 ; 另外 一 个 保持 所 有 的 软 性 
类 型 提示 在 一 个 文件 中 。 


添加 声明 


于 增加 声明 的 工具 只 能 在 Hack 文 件 (任何 模式 ) 中 使 用 。 它 是 类 型 检查 器 服务 器 端的 一 部 分 ， 你 可 以 通过 执行 下 面 的 命令 行 来 调用 这 个 工 


$ hh_server --convert my project my project 


在 --convert 标 志 位 后 ， 这 里 有 2 个 实 参 : 第 一 个 代表 我 们 实际 要 做 修改 的 目录 文件 来 。 第 二 个 代表 对 应 工程 的 顶层 目录 文件 夹 。 这 种 两 者 分 离 的 方式 允许 你 限制 修改 范围 为 项 目的 一 个 子 集 。 当 你 正在 
处 理 一 个 大 型 代码 库 的 时 候 ， 这 可 以 帮助 你 保持 在 一 个 便于 管理 的 区 块 大 小 范围 内 工作 。 这 两 个 实 参 允许 相同 ， 最 好 的 配置 情况 下 ， 这 个 工具 一 次 能 处 理 的 代码 越 多 越 有 效 。 


相 较 类 型 检查 器 对 Hack 文 件 进行 分 析 的 过 程 ， 这 个 推理 过 程 显得 相当 漫长 ， 这 是 因为 它 并 非 函数 级 别 的 。 例 如 ， 当 执行 一 个 拥有 未 标注 形 参 的 函数 时 ， 它 会 查找 函数 的 调用 点 来 查看 传递 进来 什么 样 的 


实 参 。 如 果 它 找到 了 一 致 的 实 参 类 型 ， 它 会 添加 适当 的 标注 信息 。 


移 除 错 误 的 声明 


一 旦 添加 这 些 标注 ， 需 要 对 它们 进行 测试 。 运 行 一 些 测试 用 例 是 最 好 的 开始 。 添 加 的 标注 ， 除 了 警告 并 不 会 改变 任何 行为 ， 所 以 它们 不 应 该 导致 测试 失败 ， 但 运行 测试 用 例 是 运行 代码 最 简单 方便 的 方 
式 。 此 外 ， 你 可 以 运行 任何 命令 行 脚本 。 如 果 你 的 项 目 是 个 Web 应 用 ， 那 么 可 以 配置 一 个 Web 服 务 器 并 访问 一 些 页 面 。 这 里 的 目的 是 尽 可 能 多 地 对 你 的 代码 进行 测试 。 


当 你 这 样 做 的 时 候 ， 你 必须 对 错误 信息 进行 捕获 。 如 果 你 正在 运行 脚本 或 者 从 命令 行 下 面 进行 测试 ， 错 误 信 息 将 会 出 现在 标准 输出 中 。 你 可 以 把 这 些 标准 输出 导向 一 个 文件 : 


$ hhvm testfile.php > errors.1log 


这 可 以 捕获 标准 输出 中 的 任何 信息 ， 也 包括 脚本 中 的 输出 ， 但 这 并 不 是 个 问题 。 标 注 移 除 工具 使 用 正则 表达 式 来 搜索 特定 的 错误 信息 ， 所 以 脚本 的 输出 并 不 会 影响 推断 。 


如 果 你 正在 运行 HHVM 作 为 服务 器 ， 错 误 信息 再 一 次 默认 输出 到 标准 输出 。 为 了 使 错误 信息 都 写 入 文件 中 ， 你 可 以 使 用 这 个 配置 选项 : 


$ hhvm -m server -d hhvm.1log.file=errors.1og 


在 执行 你 的 代码 后 ， 如 果 任何 软 性 的 类 型 声明 失败 了 ， 你 可 以 查看 日 志 中 的 错误 信息 。 它 们 看 起 来 会 非常 类 似 下 面 的 例子 ， 这 些 是 标注 移 除 功能 查找 的 : 


Warning: Argument 1 to f() must be of type Qint，string given in 
/home/oyamauchi/hack/testfile.php on line 5 

Warning: Value returned from function f() must be of type Qint, string given in 
/home/oyamauchi/hack/testfile.php on line 6 


需要 重点 注意 的 是 ， 标 注 移 除 工具 会 从 错误 信息 中 对 文件 路 径 进行 解析 ， 并 在 这 个 路 径 下 查找 对 应 文件 。 如 果 日 志 中 的 文件 路 径 是 相对 路 径 ， 这 个 工具 会 相对 于 当前 工作 目录 进行 处 理 。 


HHVM 默 认 情 况 下 会 在 错误 日 志 中 输出 绝对 路 径 地 址 。 这 可 能 会 成 为 一 个 问题 ， 例 如 你 从 一 个 机 器 上 收集 日 志 信 息 ， 然 后 在 另外 一 台 机 器 上 做 标注 移 除 工作 ， 而 两 台 机 器 使 用 不 同 的 项 目 源码 路 径 。 为 
了 处 理 这 种 情况 ， 你 可 以 使 用 类 似 sed (该 工具 的 具体 使 用 已 经 超出 本 书 的 讨论 范畴 ) 的 工具 ， 把 到 项 目 根 目录 的 路 径 从 日 志 信 息 中 移 除 : 


$ sed -e 's!/home/oyamauchi/hack/!!g' < errors.1og > errors-relative-paths.1og 


最 终 ， 通 过 一 个 合适 的 日 志文 件 ， 对 不 正确 的 标注 进行 移 除 是 非常 容易 的 。 如 果 错 误 日 志 拥有 相对 路 径 ， 那 么 请 确保 在 正确 的 工作 目录 内 。 然 后 像 下 面 的 例子 一 样 ， 使 用 命令 hack_remove _soft types 
即 可 : 


$ hack remove soft types --delete-from-log errors.1og 


声明 硬化 


如 果 你 非常 确信 余下 的 标注 信息 都 是 正确 的 ， 可 以 使 所 有 余下 的 标注 变 为 硬性 的 。 这 也 可 以 使 用 命令 hack_remove_soft types 来 完成 : 


$ hack remove soft types --harden lib/core.hh 


这 个 工具 目前 仅仅 接受 一 个 单独 的 文件 作为 一 个 实 参 。 如 果 你 想 要 把 这 项 操作 应 用 到 目录 中 的 所 有 文件 上 ， 你 可 以 使 用 find 功 能 。 下 面 的 例子 中 ， 该 工具 将 在 lib 目 录 及 其 子 目 录 中 递归 查找 以 .hh 后 缀 结 
尾 的 每 个 文件 ， 并 对 这 些 文件 应 用 该 项 功能 : 


$ find lib -type f -name '*.hh' -exec hack remove soft types --harden '{}' ';"' 


[由 在 严格 模式 下 ， 这 里 会 有 一 个 错误 : dowork0 函 数 没有 返回 类 型 标注 。 


10.3 ”编译 Hack 代 码 到 PHP 代 码 


HHVM 目 前 是 唯一 支持 Hack 的 执行 引擎 。 这 就 意味 着 任何 人 都 不 能 组 织 HHVM 运 行 Hack 代 码 。 如 果 你 是 一 个 PHP 类 库 的 作者 ， 这 可 能 不 把 你 的 代码 迁移 到 Hack 上 来 非常 好 的 理由 ， 但 这 种 做 法 是 说 不 
因为 这 会 导致 你 流失 很 多 潜在 的 用 户 。 


通 的 


Hack transpiler 被 Hack 团 队 开 发 用 来 缓解 这 种 状况 。transpiler 是 一 个 可 以 自动 把 Hack 代 码 库 转 为 PHP 的 工具 。 它 的 初衷 并 非 要 转化 一 个 Hack 代 码 库 到 PHP， 以 便 你 能 够 在 PHP 下 进行 开发 。 
transpiler 要 以 下 面 的 构建 步骤 来 进行 使 用 : 你 在 Hack 下 面 进行 开发 ， 然 后 在 打包 前 把 它们 编译 成 PHP 文 件 。 你 可 以 拥有 两 个 不 同 版 本 的 代码 。 原 始 的 Hack 版 本 可 以 提供 给 使 用 HHVM 和 Hack 的 用 户 。 对 
于 没有 使 用 它们 的 用 户 ， 你 可 以 提供 给 他 们 编译 好 的 PHP 版 本 。 


transpiler 工 具 伴 随 HHVM 发 行 ， 你 可 以 使 用 命令 h2tp 来 运行 它 。 给 出 你 的 Hack 代 码 库 的 路 径 ， 然 后 紧 跟着 你 想 存 放 PHP 代 码 结果 的 路 径 。 它 将 会 检查 任何 后 缀 名 为 .php 和 .hh 的 文件 ， 而 其 他 类 型 的 
文件 将 会 无 修改 地 复制 到 目标 目录 中 。 


$ 1s -a my project 
. http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/.. .hhconfig main.hh 


$ h2tp my_project my project transpiled 
The Conversion was successful 


$ 1s -a my project transpiled 
. http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/.. .hhconfig main.php 


输出 的 PHP 代 码 并 不 需要 编辑 。 所 有 的 注释 都 被 过 滤 了 ， 并 且 所 有 的 格式 并 不 保证 被 保留 。 代 码 没有 必要 进行 混淆 ， 所 以 从 PHP 代 码 的 角度 上 看 ， 去 理解 相关 的 栈 跟踪 应 该 不 太 困难 。 


一 县 PHP 代 码 被 创造 了 ， 这 里 还 有 一 个 设置 的 步骤 。 生 成 的 代码 需要 使 用 Hacklib， 这 个 库 可 以 给 编译 代码 提供 集合 的 函数 和 类 支持 。Hacklib 伴 随 着 Hack/HHVM 安 装 ， 默 认 路 径 
为 /usr/share/hhvm/hack/hacklib。 


首先 ， 复 制 HackLib 到 包含 项 目 编译 的 PHP 代 码 目录 下 : 


$ cd my project transpiled 
$ cp -r /usr/share/hhvm/hack/hacklib . 


其 次 ， 通 过 include 或 者 require 等 语句 ， 在 生成 的 任何 文件 代码 顶部 添加 一 行 代码 用 于 确保 生成 文件 被 加 载 的 时 候 ， 这 行 代码 被 执行 。 在 全 局 变量 HACKLIB_ROOT 中 放置 指向 Hacklib 的 主 文件 路 径 。 
例如 ， 如 果 Hacklib 代 码 被 复制 到 项 目的 顶层 目录 下 : 


$GLOBALS['HACKLIB ROOT'] = _DIR  . '/hacklib/hacklib.php'; 


10.3.1 转化 


本 节 并 不 会 对 transpiler 做 的 所 有 转化 做 全 面 而 详细 的 讨论 ， 但 将 会 进行 充分 解释 ， 以 便 你 能 够 对 生成 的 PHP 代 码 有 着 大 体 的 想法 和 认识 。 


需要 强调 的 非常 重要 的 一 点 是 ， 即 使 在 同一 个 执行 引擎 下 ， 编 译 好 的 PHP 代 码 相 比 原始 的 Hack 代 码 运行 效率 会 更 低 。 正 如 我 们 在 本 节 中 将 要 看 到 的 ， 一 些 常见 的 Hack 结 构 将 被 低 效 的 PHP 结 构 蔡 代 。 
例如 ， 一 些 相等 比较 操作 将 会 被 函数 调用 蔡 代 。 


transpiler 将 会 尝试 转化 所 有 的 Hack 文 件 ， 并 且 不 会 触 碰 PHP 文 件 。 它 通过 一 个 文件 的 开始 标记 是 < ”hh 还 是 <”php 来 判断 一 个 文件 的 语言 ， 而 不 是 通过 它们 的 文件 后 缀 。 


下 面 是 transpiler 做 的 最 重要 的 事情 : 


“ 所 有 的 类 型 声明 都 被 移 除 。 因 为 类 型 声明 是 唯一 使 用 类 型 别名 的 地 方 ， 所 以 类 型 别名 可 以 简单 地 删除 。 

“ 集合 字面 量 ( 见 5.3.1 节 ) 被 新 的 表达 式 代替 ， 这 可 以 使 集合 类 在 PHP 中 仍旧 可 以 使 用 。 

“ 拉 姆 达 表达 式 〈 见 3.4 节 ) 被 常规 闭 包 语法 替代 。 类 型 检查 器 从 封闭 作用 域内 查找 哪个 变量 需要 捕获 ， 然 后 生成 适当 的 使 用 列表 。 
“ 枚 举 〈 见 3.1 节 ) 被 转换 为 类 ， 枚 举 成 员 都 被 转 为 类 常量 。 特 殊 的 枚 举 函 数 通过 Hacklib 的 trait 提 供 。 

“ Shape ( 见 3.3 节 ) 和 tuple 被 数组 取代 。 

“属性 ( 见 3.6 节 ) 被 移 除 ， 除 了 __Memoize， 它 不 被 支持 。 具 体 参 见 下 一 节 内 容 。 

“ trait 必 备 条 件 ( 见 3.10 节 ) 被 移 除了 。 

“ 参数 升级 的 构造 器 ( 见 3.5 节 的 内 容 ) 被 展开 ， 需 要 声明 必需 的 属性 ， 并 且 在 构造 体内 对 其 进行 赋值 。 

“ nullSafe 方 法 调用 操作 ( 见 3.9 节 相关 内 容 ) ， 被 Hacklib 类 使 用 神奇 方法 ”call () 模拟 。 


“ 因为 集合 类 的 行为 正在 打造 ， 并 且 PHP 中 的 相等 比较 不 像 Hack 中 是 特例 ， 一 些 结构 的 实例 必须 被 修改 。 例 如 ， 这 里 的 Hack 代 码 依赖 于 空 的 集合 ， 当 把 集合 强制 转化 为 布尔 型 ， 它 将 被 执行 为 false。 


function average (Vector<num> $nums): num { 
if (1Snums) { 
throw new InvalidArgumentException( 
"Can't average an empty Vector" 
); 


// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


为 了 在 PHP 中 获得 同等 的 效果 ，transpiler 将 会 使 用 Hacklib 中 的 助手 函数 : 


function average (Snums) { 
if (!\hacklib_cast_as_boolean (Snums)) { 
throw new InvalidArgumentException( 
"Can't average an empty Vector" 
); 
} 


// http://www.hzcourse.com/resource/readBook?path=/openresources/teach ebook/uncompressed/16125/0EBPS/Text/... 


10.3.2 不 支持 的 特性 


这 里 有 多 项 transpiler 不 能 转化 为 PHP 的 Hack 特 性 。 如 果 它 碰 到 了 这 些 中 的 任何 一 项 ，transpiler 都 会 放弃 整个 文件 。 它 从 不 会 只 对 文件 的 一 部 分 进行 转化 ， 它 也 不 会 产生 和 原 Hack 代 码 行为 不 一 致 的 
PHP 代 码 。 


触 碰 


[ 


transpiler 所 生成 的 用 于 模拟 Hack 特 性 的 PHP 代 码 和 PHP 5.4 及 之 后 的 版 本 兼容 。 然 而 ， 如 果 你 使 用 了 更 加 新 的 PHP 版 本 特性 ， 例 如 generator (在 PHP 5.5 中 出 现 的 特性 ) ，transpiler 并 不 会 试 | 
这 些 ， 所 以 这 些 输出 的 代码 将 只 能 在 PHP 5.5 及 以 后 的 版 本 中 运行 。 


这 里 是 transpiler 不 支持 的 特性 : 


“ 异步 函数 (具体 参见 第 6 章 的 内 容 ) 。 运 行 异步 函数 需要 在 运行 时 的 扩展 支持 。 有 理由 相信 ， 在 纯正 的 PHP 环 境 下 是 不 可 能 模拟 这 个 的 。 可 以 简单 地 移 除 async 和 await 关 键 词 来 对 异步 函数 进行 转换 。 这 
可 以 得 到 正确 的 结果 ， 但 是 这 没有 什么 可 比 性 。transpiler 在 未 来 的 发 行 版 中 将 会 对 此 进行 改善 。 


“ 特殊 属性 “Memoize (参见 3.6.2 节 的 内 容 ) 。 不 像 其 他 属性 可 以 被 简单 移 除 ， 移 除 _Memoize 将 会 导致 转换 失败 。 这 个 属性 需要 运行 时 支持 ， 并 且 在 纯正 的 PHP 环 境 中 对 这 个 进行 模拟 是 非常 费事 的 。 
作为 一 个 解决 方案 ，memoization 模 式 可 以 通过 手动 的 方式 较 容 易 地 实现 。 


. 实现 接口 的 trait ( 见 3.10 节 ) 。 


“ 集合 字面 量 作 为 非 静 态 属 性 的 初始 值 ( 见 5.3.1 节 ) 。 这 是 因为 集合 字面 量 必须 转换 为 PHP 中 的 新 的 表达 式 ， 而 这 些 在 属性 初始 化 中 是 绝对 不 允许 的 。 这 种 限制 只 作用 于 非 静 态 属性 ， 因 为 对 静态 属性 
的 初始 化 可 以 在 类 外 部 轻松 地 移 除 。 


